Jim Lynch Codes
  • Blog
  • About Jim

Writings about one coder's stories & experiences.

Thoughts on Hosting Living Documentation

8/4/2016

0 Comments

 
Here's a post I wrote after having an "aha moment" about how to efficiently keep my living documentation up-to-date and easily accessible. Enjoy!

The Importance of "Living Documentation" in BDD

I'm been trying to really get deep into CucumberJS recently and have been reading a few BDD books (BDD in Action and Specification by Example are my favorites). One thing that really stood out to me was how much emphasis they put on the output of your automated tests. These are far more than just a recording of "what happened" in your tests runs. These are the single source of truth for  your requirements, a live page for anyone on the team to see, and a common language for your team to communicate efficiently. Gojko Adzic, author of Specification by Example, writes his book about how these reports increase in value with age and how incredibly useful they were to the "business as usual" team making small changes long after the original developers had moved on.

Hosting Your Reports Alongside Your Project

When I set my Angular projects live, I usually have a dist directory with all my minified files that are to be hosted. The contents of this dist folder get pushed to my gh-pages branch (a way to host sites for free on Github). The key thing to remember is that you can always add a folder directly inside of dist called something like, "living-documentation". In  it you can put all of your generated reports, and viola. Now your reports are live! (or as we say in BDD land, living). You may even find it nice to set your karma and protractor config files to dump the reports directly into their respective subfolders under a main "living-documentation" folder that lives in the dist directory.  
​
Eugene-sea himself, creator of the karma-cucumber-js project, responded to an issue I opened with a great comment explaining how his project is set up. He also gives a link to his cucumber report hosted on the gh-pages along with the project itself, noting that this was the most useful report in his project and that it is, "used by all parties (business, technical, non-technical) involved in projects to discover current state of business requirements". 

Living Doumentation == Automated Test Reports

As Eugene-sea states in his comment above, the reports ARE the living documentation. They are organically evolving in sync with the source code, and at any time any member of the team can take a look at them by visiting the url in a browser. They represent the automated tests and how your source code aligns with what the tests are expecting. Without hosting your test output, the non-programmers would have to go into the git repo, dig into the source code, find all the feature files and juggle them somehow... it just becomes too inconvenient and people stop using them. This is the way. This setup that I am recommending makes it so effortlessly easy and so in-your-face available that your team should want to read the reports and ​borderline enjoy reading the reports (I mean it's still work, right!). 

Putting It In A Pipeline

Doing all of this manually is the first step to seeing how it all works, but having to regenerate all of your living documentation reports every time you want to push your code can get annoying very quickly! The best way, and really the right way, is to have a continuous integration pipeline in place that will build your project, run all the tests, host the reports, and  host the project itself.  

Open-Source Vs. Commercial

If you're new to BDD, automated testing, or continuous integration I highly recommend trying to set up your own CI pipeline with Github and Travis CI. It's totally free and gives you the power to really customize the steps in your pipeline any way you want. For commercial projects, almost all the companies I've seen were using Jenkins for CI. The implementation details of setting up each one will differ of course, but overall you're really doing the same thing in both cases: running the tests, building the project, hosting all the things, etc. In an open-source project it might be totally fine to have your living documentation public (then you can show it off to the world!). However, if you have a commercial project or just want to keep it on the low you can always add an authentication step to your living documentation pages or even host them at a different web address entirely. It's just html so can do whatever you want with it. You could even create a whole SPA dashboard for your living documentation!
0 Comments

Your comment will be posted after it is approved.


Leave a Reply.

    ​Author

    Picture
    The posts on this site are written and maintained by Jim Lynch. About Jim...
    Picture
    Follow @JimLynchCodes
    Follow @JimLynchCodes

    Categories

    All
    Actionscript 3
    Angular
    AngularJS
    Automated Testing
    AWS Lambda
    Behavior Driven Development
    Blockchain
    Blogging
    Business Building
    C#
    C / C++
    ClojureScript / Clojure
    Coding
    Community Service
    CS Philosophy
    Css / Scss
    Dev Ops
    Firebase
    Fitness
    Flash
    Front End
    Functional Programming
    Git
    Go Lang
    Haskell
    Illustrations
    Investing
    Java
    Javascript
    Lean
    Life
    Linux
    Logic Pro
    Music
    Node.js
    Planning
    Productivity
    Professionalism
    Python
    React
    Redux / Ngrx
    Refactoring
    Reusable Components
    Rust
    Security
    Serverless
    Shell Scripting
    Swift
    Test Driven Development
    Things
    TypeScript
    Useful Sites
    Useful Tools
    Video
    Website Development
    WebStorm
    Writing

    Archives

    March 2023
    August 2021
    February 2021
    January 2021
    October 2020
    September 2020
    May 2020
    April 2020
    February 2020
    January 2020
    December 2019
    October 2019
    September 2019
    August 2019
    July 2019
    June 2019
    May 2019
    April 2019
    March 2019
    February 2019
    January 2019
    December 2018
    November 2018
    October 2018
    September 2018
    August 2018
    June 2018
    May 2018
    April 2018
    March 2018
    February 2018
    January 2018
    December 2017
    November 2017
    October 2017
    September 2017
    August 2017
    July 2017
    May 2017
    April 2017
    March 2017
    February 2017
    January 2017
    December 2016
    November 2016
    October 2016
    September 2016
    August 2016
    July 2016
    June 2016
    May 2016
    April 2016
    March 2016
    February 2016
    January 2016
    December 2015
    November 2015
    October 2015

    RSS Feed

  • Blog
  • About Jim
JimLynchCodes © 2023