Executable Documentation for everyone (even you)

Video thumbnail (Frame 0) Video thumbnail (Frame 1332) Video thumbnail (Frame 3015) Video thumbnail (Frame 4455) Video thumbnail (Frame 6486) Video thumbnail (Frame 11345) Video thumbnail (Frame 13312) Video thumbnail (Frame 24509) Video thumbnail (Frame 26743) Video thumbnail (Frame 29619) Video thumbnail (Frame 34032) Video thumbnail (Frame 36810) Video thumbnail (Frame 39384) Video thumbnail (Frame 40528) Video thumbnail (Frame 41869) Video thumbnail (Frame 44303) Video thumbnail (Frame 45496) Video thumbnail (Frame 46908) Video thumbnail (Frame 56560) Video thumbnail (Frame 59190) Video thumbnail (Frame 63859) Video thumbnail (Frame 69175) Video thumbnail (Frame 71116) Video thumbnail (Frame 73941) Video thumbnail (Frame 75233) Video thumbnail (Frame 76896) Video thumbnail (Frame 78305) Video thumbnail (Frame 79542) Video thumbnail (Frame 82833)
Video in TIB AV-Portal: Executable Documentation for everyone (even you)

Formal Metadata

Executable Documentation for everyone (even you)
Title of Series
Part Number
Number of Parts
CC Attribution - NonCommercial 2.0 Germany:
You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal and non-commercial purpose as long as the work is attributed to the author in the manner specified by the author or licensor.
Release Date

Content Metadata

Subject Area
Executable Documentation for everyone (even you) Sometimes good documentation makes the difference between just another dead github repository and a successful, widely used library. But writing documentation is tedious and boring and maintaining it ten times so. But wrong documentation is sometimes worse than none so updating it is even more important than writing it. ······························ Speaker: Nikolas Martens Event: FrOSCon 2014 by the Free and Open Source Software Conference (FrOSCon) e.V.
Keywords Free and Open Source Software Conference FrOSCon14
Source code Freeware Term (mathematics) Multiplication sign 3 (number) XML Open set Condition number
Digital electronics Different (Kate Ryan album) Thermal radiation Bit Musical ensemble
Web 2.0 Software engineering Moment (mathematics) Right angle Code Inverter (logic gate) Twitter
Software Personal digital assistant Software developer Projective plane Moment (mathematics) 1 (number) Software testing Software framework Right angle
Ocean current Web page Slide rule Functional (mathematics) Code Multiplication sign Projective plane Moment (mathematics) Electronic program guide Code Revision control Medical imaging Mathematics Factory (trading post) Right angle Software testing Software framework Freeware Error message Reading (process) Condition number Library (computing)
Point (geometry) Functional (mathematics) Presentation of a group Open source Code Multiplication sign 1 (number) Student's t-test Client (computing) Computer programming Formal language Software bug Subset Programmer (hardware) Latent heat Sign (mathematics) Goodness of fit Term (mathematics) Different (Kate Ryan album) Software testing Circle Router (computing) Descriptive statistics Physical system Form (programming) Area Dependent and independent variables Hazard (2005 film) Software developer Interface (computing) Boilerplate (text) Interior (topology) Line (geometry) Instance (computer science) Unit testing Word Process (computing) Logic Query language Order (biology) Right angle Natural language Quicksort Freeware Router (computing) Library (computing) Reverse engineering
Point (geometry) Group action Software developer Multiplication sign Electronic program guide Formal language Neuroinformatik Programmer (hardware) Strategy game Term (mathematics) Different (Kate Ryan album) Telecommunication Order (biology) Authorization Triangle Energy level
Decision tree learning Software developer Multiplication sign Unit testing Mereology Formal language Programmer (hardware) Latent heat Word Personal digital assistant Different (Kate Ryan album) Internet service provider Triangle Software testing Physical system
Word Decision tree learning Personal digital assistant Virtual machine Plastikkarte Data structure Client (computing) Table (information) Code Virtual machine
Standard deviation File format INTEGRAL Fitness function Unit testing Function (mathematics) Variable (mathematics) Perspective (visual) Subset Process (computing) Positional notation Computer configuration Order (biology) output Speech synthesis Software testing Right angle Quicksort Table (information) Descriptive statistics Physical system
Data management Positional notation Code Function (mathematics) Product (business)
Programming language Code Multiplication sign Execution unit Projective plane Instance (computer science) Function (mathematics) Client (computing) Disk read-and-write head Computer programming Data mining Latent heat Goodness of fit Mathematics Data management Personal digital assistant Function (mathematics) Software testing Right angle Social class Physical system
Covering space Process (computing) Software Term (mathematics) Projective plane Online help Right angle
Web page Open source Computer file Code Multiplication sign Source code Virtual machine Web browser Mereology Perspective (visual) Rule of inference Computer programming Formal language Neuroinformatik Product (business) Medical imaging Latent heat Goodness of fit Different (Kate Ryan album) Single-precision floating-point format Software testing Error message Physical system Area Uniqueness quantification Software developer Projective plane Sound effect Bit Instance (computer science) Word Arithmetic mean Process (computing) Software Repository (publishing) Order (biology) Website Right angle Problemorientierte Programmiersprache Reading (process) Reverse engineering
Functional (mathematics) System call Hecke operator Computer file Constructor (object-oriented programming) State of matter Execution unit Set (mathematics) Mereology Graph coloring Neuroinformatik Number Latent heat Software testing Abstraction Traffic reporting Game theory Descriptive statistics Physical system Injektivität Projective plane System call Message passing Personal digital assistant Order (biology) Interface (computing) Social class Quicksort Sinc function Library (computing)
Point (geometry) Functional (mathematics) Constructor (object-oriented programming) Code Parameter (computer programming) Mereology Perspective (visual) Field (computer science) Power (physics) Programmer (hardware) Latent heat Software testing Abstraction Social class Form (programming) Physical system Dependent and independent variables Projective plane Category of being Word Personal digital assistant Interface (computing) Social class Spectrum (functional analysis) Spacetime Library (computing)
Constructor (object-oriented programming) File format Personal digital assistant Content (media) Convex hull Function (mathematics) Position operator Parsing Social class
Code File format INTEGRAL Multiplication sign Software developer Sampling (statistics) Staff (military) Frustration Unit testing Mereology Product (business) Word Latent heat Different (Kate Ryan album) Telecommunication Energy level Cuboid Software testing Object (grammar) Extension (kinesiology) Abstraction Physical system
Boss Corporation Code Physical law Extreme programming Code Computer programming Element (mathematics) Power (physics) Word Arithmetic mean Goodness of fit Latent heat Term (mathematics) Different (Kate Ryan album) Reading (process) Form (programming)
Domain name Goodness of fit Group action Presentation of a group Word Integrated development environment Demo (music) Constructor (object-oriented programming) Interface (computing) Expert system Student's t-test Library (computing)
Constructor (object-oriented programming) Code Software developer Code Bit Computer programming Formal language Latent heat Word Mathematics Goodness of fit Keilförmige Anordnung Extreme programming Personal digital assistant Different (Kate Ryan album) Interface (computing) Software testing Software testing Codierung <Programmierung> Escape character Social class
so about having the time at the 1st and so welcome to my talk it's called executable documentation for everybody even for you so I wanna show a couple of things about executed the condition
what this and so on but 1st of all I wanna know about you know that was never heard that term would would doesn't have any connotations with can say on that that's what about sort of like how nonbasic maybe a 3rd of the people who just want to know what the hell I'm talking about that's and the rest of you some hands was heard of it like you
would use a get 41 2 3 again yeah like OK with things that well I mean there's nothing less than a 3rd of so and who was was actually using its or in his company and his projects but yeah depend on music circuit so maybe it the question later again and then you can tell me if you're using it the same way that I see it because it means a couple of different things so I'm going to do 2 things 1st of
all I'm gonna buy explain what I think that it is or what my definition of the soul executed documentation thing as so I give you the why hole and what of of it and then the 2nd thing is I'm going to present you docs which is publishing tool roads for example the 4 executives this for executable documentation so 1st a little bit about me that's me radiation from the heads and
correctness and my name is Nicholas Martin's I am freelancing software engineering coach now in Berlin everybody anybody from the linear the whole whole left side of the and so on and from the city and you can find me on Twitter on the web or also get out and they should have for me but you can also find the right here at the moment and I'm also called organizing a Coding Dojo inverted
so the the people from the linear if you ever wanted to know what according Dodgers adjusted uh check it out it's next Thursday it's coming up and everybody was every billion to stop by its it's fun always that that's what I'm doing and let me tell you the story of Y and and during this talk a lot like why why this is important to me all of this all started and I have to
make sure they were topics when the software design and the other one's testing so I'm really into those 2 things and when I say testing of course and automated testing because well and developed developers a lazy and I hate doing stuff manually coding is hard enough I don't wanna do unnecessary testing so I tried to automate as much as possible and so because I also have a strong case of the not invented here syndrome like most developers as opposed I needed
to do my own mocking framework because there aren't enough mocking frameworks PhD at the moment are ever so I needed to do and another 1 I called it blocks the uh and this is where it all started actually I put a lot of effort into this project and can be also used to that of the research that where I was working and so on so I wanted to make this really nice so I put a lot of effort into documentation right cosegmentation is very important and if anybody was seriously morning and saw the talk from called uh he was having a lot of issues with so badly documented projects so I didn't want to have anybody to this problem so I put a lot of effort into documentation so I made a really on this what you do nowadays I wrote about
the main features like why this is better than all the other mocking frameworks because curious would exist otherwise a I and I wrote installation guides erodes a quick start where you can just copy and paste the code basically and uh and it should work and I even wrote like go like this is a very long basic usage so it's like 3 pages for pages long how to use and everything and I was very happy with myself was was like that was the 1st project of modern closely for myself that I actually documented that well so was quite content except that it was wrong if the codes I put in the example was not right because I just forgot to update some API changes I did and it wasn't the documentation in more so yeah all data documentation anybody ever had the problem of all data documentation so who's never had the problem of all data documentation we get it is avoided altogether so that's not very nice so yeah I have the same 0 at the same problem actually somebody pointed out to me is like I think people you know doing this nice basic musician everything but they actually parsing error this this method doesn't exist and I'm like 0 that sucks but so I started thinking what would you can do and I actually had an idea and this is where all started I was like let's take all this code from the documentation and put it into a PHP 5 because then I can just make sure that I can just ask deposit is this is this right amount and of course I didn't want to use the nice comments on the role of so I put them in the PHP 5 as well as comments obviously and so on and that's it that's the executable documentation because you still have the condition of the project and now we can write so you can do away with the reading I just I just deleted it all and it's there because revisions and everything but it's not so that's not and current version and I'm just executing this the slides if I it's executable now I just I actually put it in my test for the random let's of the sea ice overtaking annoyed time I see this little green light going on and all everything's all right to actually still passes and if if I would do the same mistake again this will turn red never happened since then but it matters so I know if the documentation is still up to date and of course for the the cold the commons as the as the static but they are there are not that important if you wanna make it running so I was happy and that's it that's up that's executable documentation is this running away from from what you use different again you have to terminate 0 0 so this is this the best definitely and so decided this was very fun and sperm gun and to the written code now was developed here we're writing code for a living was not
almost OK so sorry about the code a more solid that this 1 it's cut off on the left side but it's due huge you just have to imagine a bunch of policy science so I kept them out that you can still read it so this looks like this is this is the import of my market framework don't get into that but still images on show you how I post notices actually looking like so it's validating the syntax of ever make a syntax error edges make spelling errors also on it will turn red and I would know it but then I started noticing that I can't even do more because I can also validate the functionality of this smoking forever I can just say OK why don't I actually do call the full method and then assert in end if it if the true cost what's called with that was called the busses they return to the right thing here because this is the it's the documenting how to use the library and it's also of validating functionality and a couple of people saying I know what this is this is a test This is a moment that's right and that that's true were exposed usually a tell people right into the automated test and you get the documentation for free but this
would just happened the other way around this time I wrote the documentation and suddenly I had a test that's because interchangeable the sexually were work so and yet they're just the same thing basically accreditation testing and all I have to to prove that it works both ways very nice so there's obviously and works is very easy with libraries because well that's kind of a library is a program so it's really easy to write another program which is an automated test to use library right so this is using the same goes for public API because they have other programs as clients as well so am I wanted to be used for a full API is as well and I think ice is especially important because what using from working a lot with with public API so they should be used graceful and it's usually terribly documented anybody else has this problem with a public API and they just never completely cut documented usually exactly the set this thing I need is not in the documentation and I have to reverse engineer how this whole thing works and then got all its open-source usually so I can do that but it's the hassle so I thought you know why don't why don't I just use the same approach where the eyes I will have as an executable documentation of this thing I would know that works and stuff and I'll be happy so and this can be done very easily and you just here just request of some query from the point for bar and expects from that's the with some data has a very imaginative from not doing much this the API but you just can't do it like this and of course here we have a lot of unnecessary boilerplate code so to say we have this router which of course he is already instantiated but we need to get it from somewhere and then like we have the society goods and everything and this is not very readable I mean like 4 phenyl develop hazardous but what if somebody else wants to understand what some non-technical stakeholders once anomalous API works and then you can show this and like OK this sort works now is very easy to understand and you'd be like way what's the dollar sign during this this is this money for his so just 1 confused most non-technical monkey few programmers so this really is a trick you just wrap this ugly methods with nice wrap methods we just call it when I request some gray area to for them together from the above then the response should be some data now I didn't much just ranked as 1 line in another line but it's now it's readable and them and then the last thing is that it's using a natural language and also on ubiquitous language the chief was like that and pronounce ubiquitous things so that meaning that everybody this a language everybody understands everybody knows helps out to uh to use it and the you have a good chance that you're non-technical stakeholders knows what a request this and what responses because if you want student who is interested in 280 eyes he needs to know those 2 things at least but it doesn't need to know what a router but what about the job of routers so use use different words change language and this is a lot more readable and so on with this with this little trick you can now not only the right documentation for eyes libraries you can just right it for everything for any program you ones any program that does anything and so now I run full circle and you might say I have heard this before this is exactly what behavior-driven development but the approach from the other side to start with documentation and you end up with specifying all systems and so who knows was familiar with behavior during development OK that's not was hurts example-driven development before what who is familiar with her acceptance tests during development the and about age giant testing the last area OK so that's the I did make up these words he that they existed just not very popular and I guess the didn't development this by far the most popular from what but to mean they all mean the same thing they all uh just describing the system using the examples and specifying the I actually prefer the term I ask that they have put the step I have I have I don't like the evidence development the word of the term because people I've seen a lot of that practices of other so who is usually people when they when they say we during the evidence development it means rewriting old you test who's right was testing through you are think it's synonym you have to OK to enjoy it you of that you there and probably not so 1st like yeah yeah yeah you recording well I'm I'm totally on the sides with Uncle Bob when he says that don't don't test I only have to if you want to test UI itself and you will see but if you want that test any of any policies and in the business logic donors do I that's the worst of interface you can use that's very fragile the test usually funding you probably facing on this problem success you they break easily the great for reasons that have nothing to do with the thing that you're testing because there's just too much in between so when when I'm talking about these things these don't think about cucumber instance selenium and like browser-based automated testing this is not what I mean I mean I and talk about relational before which is just describing functionalities in terms that everybody understand in only because this language and stuff and this is why I'm usually not using behavior-driven development but I'm talking about specification by example like that term a lot better and so I'll refer to its with this term from now on but you can just substitute in your brain you don't like that term you can use any of the other 5 that you want we understand each other so I like specification by example because it has this word specification in which I think it's what really comes
bound to everything you have this interchangeability of present documentation they're basically the same thing and specification is the same thing as well as just comes before handing and you know out you describe the system employability that mutation describes system after you build and test described the system in order to uh to validate the functionality but is all descriptions of the system so usually goes the other way around usually you start with the specification then implemented as a test as an automated test and then in the end you get the documentation kind of for free because it just the same thing but it's it's not that easy because you need language in it in the form of a description that fits all these 3 means and they're they're quite different and specifications you wanna use sometimes in a very short what how we gonna do it so you cannot describing in very detailed way to describe the a kind of abstractly and in tests obviously you have to be very specific because they have new 1 automated them so they need to be like very close to to the to the system unit testing language wise and documentation and you have always you have the system so you can rely on and you can say we do this and that and then comes out so languages is different but there is a way of to unified 3 which is examples and this is why I like the term specification by example
because it has a 2 main points of this whole approach
which we have a driven developments doesn't happen because it has nothing to do with like that like behavior-driven that means like driven by behavior and never really got it and then authors not happy with this term in the morning when he came up with the but examples like the main point because as it turns out it's really nice and tools
to communicate with each other and put you on the left side on the right side is the developer guide history time and and to the left side of the business stereotypes of the words of and so on this tool parties have a lot of time and trouble understanding each other because they speak different languages almost they have different concerns programmers a concern about the details all the argued that they really love and getting their hands instead of using the ends of business people they have to think about in a hot money mostly out to make money in to contain 1 of strategies and stuff like that very very different levels so communication is hot and if you use we use examples of that CD behind us occasion by example in order to to bridge the communication gap and an example of this is that we already had when I request some criteria that I should get some data this is just this is a very simple example so it's not hard uh and to formulate but it's really hard to come up with it and we've been doing that for a like a year the some of the research group of computers working and it turns out that's like the biggest problem to come up with good she examples and and the concept of the example works kind of like this let's say you want to describe this triangle instead of just like drawing the whole triangle you can also just concentrate on these edges and you still have the
triangle specified there and you can almost see it visually right now but you only concentrate on the important things on on on the edges let's say don't take military because your edge cases and that's not a specification you that's the kind of works like this but still and that's that's by far the hardest part like who's was using data-driven development and organized as to get right and any of that approach in developing regularly just want to get the is it later on holes experience was coming up with examples the you have to do it so what do you do with to a lot of questions it made many what happened and so you know he's saying that using a that for you I testing mostly is so you don't come up with examples small like she weighs so you you click through its so normal usage of the system you testing automated again so this yeah but writing unit tests with data providers that's very close to it as just at the formulation is different language and the words using is different but the approach is very similar but but that's the better executive the differences unit tests are usually written for programmers and these tests they're written for everybody so everybody should understand them and and this is why I like it so you can combine these 2 things I just wanted to show you like a whole what I mean with examples I'm going to give you examples of examples and let's say we're working at like Amazon and some of you know merchandise company and this is us we work through the programmers and comes to us and is like you know I have an idea let's give free delivery to all the VIP customer so you know we have incentive for European customers and on but so that's say only if 4 5 articles and only for the books right and then the eagles like by things and you like what should I do now and so this is not even that far fetched a bike in my experience a lot of times you're really just get like a little sheet and everybody's queries about this user stories now right and supposed to just specify the whole thing like you're right on on 1 tiny part what it was supposed to do and then you just do it doesn't work so let's have let's describe the same thing with examples 1st example would be the objective people
because some with 5 books in the cart gets treated that's like that
the canonical case but at the customers before but in the car doesn't get the opposite and regular customer with 5 books
there's different every need because some of the key customers but if you have 5 washing machines in this card is not supposed to get through literary needed so that's actually something that wasn't specified before because the
owners that's OK with 5 articles but only books but you like we weren't sure for example but this case like if he has 5 books and a washing machine should he still gets free delivery or not or should he get free delivery for the books but not for the washing machine what should we do in this case and so this is this this is a nice thing about the writing examples like that that you actually start thinking about it in in this detailed way and you can communicate with your with your client about edge cases like this and you come up with them way faster then when you just a gold on coding because then you find such cases where coding and this way you find them beforehand which is still in my experience the biggest advantage of this approach so With this is exactly the same thing as the scenarios you have haven't convergence but I the 1 used the buzz words yet so and um but this is exactly same thing and so you ever who knows 13 distilled cucumber against but don't worry you'll you'll see later what uh what what this is and we're now you have these nice examples and so you can put them in a structure you can for example put them in a table
and you can just say OK let's have a column for customer hi and what is orders and what the delivery should be so you have the typical input output description of a system and every system can be described using as input and output this is what the system is by the Phoenician and then you can just sit at the table you can say OK we at the guy with the customer with 5 books should be free if you folks should not be free and so on the and just what I wrote down and sentence before and and so you just you see you have 3 variables all 3 of them that you have to input variable 1 output variable and you can use tables and people are doing this for example the fitness of fit as a tool that that's that's that's more like job people anybody using that of fitness for that sort of stuff what you really doing everything and so you so you mixing acceptance tests and unit test and you again and for integration tests or acceptance has used this way and this is a really nice format because it's so you can see it you can read it very easily you can see something is wrong and why and but that's not very flexible that's why I prefer sentences also because I can write them in cold and like this and it's way more flexible so you just you just right and you just come
up with these happen methods as you say but there OK that'll be fine because they help you it is right given I review key customer and then given not have a unified books in my best so the speech he so we cannot have any inputs notation so we didn't like that uh when I checked my delivery options standardization before it and this describes system scenario exactly and also it's very flexible you just have to write a couple of methods but that's a hard right we do this all the time and and they're not even that hard to implement and so this is nite the business perspective
you just enough about away from I've been using exactly this and have been showing as like the this business stakeholders of
research going this cold and they were not very happy in the beginning but after 2 or 3 weeks actually started being able to read it and they could read it just as well as anything else you with this weird notation of having you you know in big replaced in Figs they they were fine with this so this actually works and I was quite surprised that you know I've never get recode but they did well there were that were the product managers there that's why I could try his real experiments and I think you can do that with external customers like hearing this code yeah you will yeah but I have a better solution but as you'll see in a 2nd so I just want to make of anybody's interested in there like how you would actually of implement these methods you take the
inputs as good as it can origin just use real entities like the customer and you make communities and in the in the books in my basket method you create a basket instance and just for the books really really straightforward stuff that then you get the you need some class for some instances that decides whether or not to deliver should be for free so I call this the delivery manager and we just created Delivery Manager given the customer and the basket and asking should to speed it should disappear if we are not and the same thing but this just checking validating the output as data delivery should be free so PHP units fetuses assert true this is free and and they say well this is mine could also be in the test because I think it's almost readable right even for non-technical people but if you if you write standard literature before you get the more readable uh and so it's not as there is no magic behind like the system of using the head of cucumber that this is what what they do right they just match sentences to snippets of code that says you don't need a tool to do that because every programming language already knows how to match the sentence to a snippet of code and it's called the math so and I never had the need of using it for that and now and this is a specification by example for me how I defined and
I've been using it a lot and have been using for for 2 years now and if all my own projects I always specified in this way and so that was really nice they haven't done it too much with the clients it because of that's still a lot of educational work you have to do with the clients and because it was yeah you have to write these examples of the beforehand and so on that means you have to start thinking about what you wanna do before you do it and I had a lot of people don't like thinking about what they wanted to just below just dumping everything on on the program as they don't like thinking about what they actually want to have but it's that pays off once you get there so there's also book uh with the time this was a case for example this is what I call it this way and it's a really nice
book but when it comes to describing the terms when comes through were making up new terms mostly and that's that doesn't help with how old to use it it doesn't make it doesn't explain very well or all and the whole how to how to implement it in in your own project something that but is it describes the whole process really nice and that describes a lot of other teams were using it and experience with it but it doesn't say how to use it accepted so I this is the
subtitle of the widely you quoted subcaption here's how
successful teams deliver the right software and so I think this is a really nice sentences no surprises is on the cover because it's the hardest thing is usually to do the right so that software not to and then describe like this this is
us again this is the developer poor guy because he has to work with the machines there really stupid and we have to teach of something that's terrible but gets even worse we also have to talk to all the business guys who hates uh thinking about what they want to do it usually don't know what they want we have to figure it out and then they change their minds other the times it's terrible so we have 2 main purposes we have worked with the with 1 doing everything we have that to do what 2 things right we have to create but 3 or free software which is hard enough but even harder sometimes the right thing that's talk to read we have to build the right thing because if we make the best error free uh features full featured software is completely worthless nobody wanted of knowing needs and if it's not this is not the right thing and so this is really hard to do usually it's hard to figure out what the right thing is for the business people but some are really good but then we have to understand what they think the right thing right so to make sure that we implement correctly we use automated test this is a really nice way to make sure your software works as you you intend but that doesn't mean it works as this guy text so what we do then is we write specifications and so on well this this is what what we did in the eighties right waterfall approach like the role of pages and pages of specification specified everything and then we implemented it and through a specification basically because it was wrong in many ways and then we wrote pages and pages and pages of documentation which shows that was already every 2 years of something that was was outdated and but using and like using the executable approach but they they just transform you just write specications and then implement the as test and then documentations commodity and so that it helps you to to do the right thing not only the thing right but the right thing and um as I said how I do it this I just write code for the specifications because that's OK because developers of that so so as I said I don't quite follow the approach of of cucumber where write a text files plain-text files with the with the scenarios in a domain-specific language and then that gets parts and then you have this huge tool that does nothing but parsing sentences so called comes out of it and this is completely unnecessary because programming languages already of our capable of describing these things and also uh and then I think like cucumber like he had always say well that this way the business stakeholders can write this in areas themselves right but I've never seen that happening at a don't believe this will ever happen has anybody ever seen this happening like competing technical person writing a test scenario themselves it's not so I also think they cannot do this initial to the and the business stakeholder shouldn't right the scenarios the specification themselves and the developer should write the specification themselves neither this needs to be a collaborative processes needs to be done together with as many people as possible and with with many as many rules as possible so that the analyst should be involved in writing specification the QA people should be involved in writing the specification because everybody has his unique approaches unique perspective on things so and in order to write a good specification we can only do it together so why not do it in court because a it's easy but then the documentation can be read by non-technical people themselves and should be able to because we're using ubiquitous language using the language everybody knows so they don't need that shouldn't need to develop to find out how the system works and before all every projects that that weren't employing but executable documentation I got at least like every day or every other day to call asking so how does the system work again like can you please describe to me and of course I don't know anymore because what do I know what the 2 weeks ago so I had to go to the cold and and reverse engineer LibraryThing words and then you know come back to ever called me and described to them and I hate doing that because I hate reading code and hate reading my own code that's so I am the way to avoid constantly having to look up again how things work and stuff and this is why I just gave those people access to them through the through the code that describe system but I don't that was not an ideal approach because it was still hot spot them to read it was hard for them to find that they had to actually installed gets on the computer and then check out repository which was like several hundred thousand files and then they have to think that I was not ideal so what we did instead is a we made an HTML put off this of this documentation of this and so we know that was very ad-hoc and so but that still work nicely enough so it did nothing else but parser files and showed it quite nicely in image to help but then after I talked about specification by example last year the frost gone we talk afterward and people were like yes you know it's really nice having all this cold but why not show it as HTML my not make like tool open-source tool for it and I thought that picture good idea let's do it so I started doing it and this year actually have so and I can talk about this as think this is really nice is basically that anybody ever see in last year's means that last year it was in Europe is that this is the uh so this is the follow up on it if you if you may be remembered as the decade everyone into a program that exports it as as HTML so people can read it on their own um and then once you have this once you have this nice uh browser for source code everybody can
read it and you you have a single source of truth which is a very nice site products of executable documentation because people stopped discussing unnecessary stupid things like how does the system work a lot of times if you ask the people how does this like in work when is a trigger toward the containing get 3 different answers because nobody knows everybody thinks they know but nobody does not the only body the only instance you have with that actually true is the cold usually and that's only accessible to developers and even break them as I said I didn't like writing and reading but if you have this documentation that you know it's true because it's itself validating and everybody can agree to and the 2nd nice of side effects that you also you unified language so the and we had 1 entity called topic but it was also called keywords all posts it had like 5 different names but was the same entity and then again depending on if you ask the development this the moral of this the more marketing you had like 5 different words for the same concept for the same entity that was very confusing a lot of time and if you had the single source of truth is that the city could have the documentation and people have to to agree on one language on 1 4 things because it's cold and it doesn't like and then you hit the beauty as well but the meanings anyway so the and so now I think it's a good time to to show it actually uh to you all looks like well that's a little bit too far
ahead and just wanted 1st I want to show you is this so
you will hear what the hell I the system
documentation as it was of the the next so as you can see it really
put a lot of effort and it and there's like color coding everything and and what is that then if I I put the into the eroded testified called introduction tests where I put the and but I have a lot of of other test so this is actually the specification of the whole library but that shows you how to create mock how to filter functions so the injection works and yet this introduction test and then what I do with it I just posits just read that read the files and so showed them in uh in a nice readable way so check return value test PHP becomes just check return value and so also on the right side is the the numbers which indicate how many test cases are in this file and how many are passing or failing or incomplete so and it's also integrated with the sea that just and sends using from the CIA and then at the end I just have a lot of the curl call that sense the report from Dutschke units to and 2 docks and then there's parts and matched up with the them with the test cases so it it also gives you an overview of the whole of the project state like if you have a lot of in computer s or which features are still incomplete because then again like you can think of each file as a description of 1 specific feature and then when you open the the introduction test such huge here this variable yeah it looks like this yeah is the public function test basically usage so it's that needs to because test because I didn't want to change my future units of settings so it finds it still has some of executable function and then I create my own bunch of classifications that I needs in order to form through work with it so I'll define your class and and so I can do it's like again and again and then In the end and you know I I just yet mocked 3 get the mark and as you can see the commons are written in marked down so they can contain any uh but there also and can contamination and stuff it's all the that that and this is sort of looks like so we have this in introduction test with the message good that are displayed
some has 3 sections and they're also colored green because the passing if not there would be ready and then the marked on the comments of was marked on displayed as HTML you can also do like nicer JavaScript thing is so hides the class definitions because there's a huge generically and usually can inferred from from the code itself so yeah so it just looks almost exactly like the real from get up but it's actually executable so I know if it's wrong and it's also nice browsable because you have all these other professors on the left side and you can also just axis functions with this and I also wanted to show other forms of education so this is the introduction to test this kind of special because it has a lot of commons it describes the system like from the word perspective the end of the spectrum that has a lot of the comments that I talk a lot about the system and doesn't have that much code but the other test cases all specifications and have you have more code so they read is that many negative bigger where is a nice 1 words that's the first one so you just have to create a mock text that test and then as a given in this class definition when I create a mock then this property a a should be be and so on so I describe the system of just words even goal I could say because it's a library so as I could just write the code and it would still be very readable maybe even better readable because you could just copy pasted as it did in introduction to test but this way actually helps myself because I can like I can read it better myself and also people foreign to the project you don't know the internals and don't want to know what entrance and can can understand that and then have a this is this gives also parts of course and it shows that that's displayed like that and as you can see I am at this point I also powers the cold and displayed in a different way by stripped the best and I also turn those CamelCase things into into space sentences and I fill it in they the the arguments which are in the end so here it says then the property called should be false so it's that you don't have to go to underscore replacement at which I to think this is going thing be so you can you can do that you can you can parse code in any way you want if you have to use this for an API for example you can you can you can have a like a specific field of for the request in a specific field for the response so there are also very like easily understandable like displayed user to understand so you can do anything with that uh and that this is just the way easier to read than the than the code I think and also so that people use in like that better than because everybody it was not a programmer definitely so any any questions to that of take of anything you you want to see here but
I mean it's public you can just stick around it self this if you
want laughter OK but I was just a really quick demo and as whole
it's done it's not much
magic just take the kids 45 I posits
into a structured format containing the class of the methods in the content and so on but market marked on everything did and then adjust the output is it as HTML all of this is done on demand right now so directly I don't do any catching up because the need to because of but it's very static anyway since the fast enough but of of courses could so you have to catch that that would show instantly like in the case of anybody cares and using that pitch people the from the indicate that it's a very nice has a little yeah that works so very nicely and assassin and stuff marked on parser user passed on from it was it's just where credit is due so this is the problem reasons so just a recap what was done in that
sophistication by sample of 100 hydrogen development is about communication between these 2 parties between the developed of between the technical staff and an object so this is a problem that a lot of companies have like depending on the size and then the colleges to different extents but I've seen is everywhere that is just a really hard for these 2 people or 2 parties to communicate with each other and a lot of misunderstandings which leads to frustration which leads to words words products so that's helps a lot to streamline uh the way people think about it and to they communicate about it and we do this using examples because this is a format that is universally applicable and sperm is on you can have examples in any level of detail you can vary had very abstract high-level examples and you can describe very specific parts of the system using examples but it's always the same approach no matter on what's abstraction so that you can use this for future for unit tests as well as for integration tests you can always have the same format which just makes it a lot easier to approach and so and yeah we examples are a specification artists and other contagion at the same time and to transform the specifications into automated tests using this method says get by sample and then and you can use boxes to access to the documentation itself but yeah that's picture optional you can just read the code as well that already out yeah I think that's it but not quite there you go as I said I didn't talk too much about this sophisticated by simple today but if you are interested in more than just read the
book which I showed of the working the form of a check out that what the North says about because of he came up with the term as far as as I found out and I think that what he says is still very close to the original meaning and is not too much so spoiled by the whole word to come with me that some approach and he also has a very good talk if you if you don't mind reading too much if you like watching talks and this this called how to sell beauty to the business and that's that's a very good explanation Aldus they're even for non technical people simple want convinced that your your boss then you can show this talk which isn't a and what I'm giving elements of duties that everybody should read clean
codes who is not a king code of the ball again to so if your programming it's really I read every 4 years and it's just like you forget things and assisted by at the and so if you're into Agilent stuff which different checkout extreme programming which is like that the father of agile and still in its purest form I think and I also I can recommend that the lean start-up it's a book and above so just stopping ways and I think the whole agile movements and this executable documentation is a very agile method as well because it just it is stop waste such as waste it is if you write a specification and away later and you just wasted a lot of brain power law paper 2 or whatever so where we don't produce things we we we throw away later whenever we have active artifacts that we can reuse we have less waste and more from the everything while I was it if you want to check it out so you so that you can
find books about bodies about the environment topic and for good or whatever you want and you can find this presentation and so were lots of other things that are constant August well uploaded hopefully tomorrow may be too much the Newton and so if you want a returning student so there are much fewer 1 2nd you are really quick 5 minute demo of the tool that we've done OK that's the only question that we have actions and that of Reynosa out any questions yes I'm going to this 1 that would be a so the question is if I can show up of what the business would see and this is
what I was showed you um and it it's it's there it depends very much on the domain and and this is usually very readable to domain experts because they know the words and their intuitive but just if never use of mocking library then you understand like what a classification as and when I create a mark but this is usually what I showed to yes 1 of the I I don't mean that they're the quote that I implement like like this so this is what the business users see I don't
show them the code I don't show them
how I implemented and I just showed him that the
specification or I don't show to and usually we come with a up together and created together so there a I don't just show it to them and but I'd like if they are interested in the code of the goods themselves that then you you show but that's not the case this here is this is 1 of the things you know so if if I'm using this approach with other languages as not English or as will be the uh yes I've actually have done the coaching with the with the guy who didn't like English that much and I introduced into specification by examples and he preferred German so but it was a little bit upwards so we wrote under Norman escape and a class and the you you vendor-specific bonds are the best so they are equivalent keywords and you can just translated but if you're referring to whether or not at all nodes are presented correctly and parsed correctly I don't know if she had tried it out but I mean the the ad and if if you find that they're not words you can dispatch again the rest of the and so where the difference would make the between behavior-driven development as it's very similar to that of the differences that interested development you write Automated Test encodes that's only programs can read and behavioral development that's that's the idea that such a that so that's basically the only change it has a lot of and that has a lot of implications that 1 change but that's that's basic change our bellies for me and I had a better yes people remained radius the answer different things but that's that's what it's the middle of the any questions about