dan sandler

Thank you for documenting your work!

   A pain point of any development stream is documentation. Ironically I love it, love it to pieces. There is nothing like reading up on an API and it clearly lays out the steps on how to use it; with examples! Sadly one of Agile's values is working software over documentation. This is nice because of the laser focus on the final product. For everywhere else, it's not so great when documentation is expected. 

"When do we document?"

     Documentation usually isn't created when development occurs though it's the most ideal place. Document as you go right? No, not really. Documentation if at all happens afterwards. From my perspective when code is written its destined for one of two directions; code to develop applications or code that is used to build libraries of reusable code. The former code is almost never documented while the latter is done methodically. 

     When coding for an application, documentation of its makeup can become stale quickly as the app moves through its life-cycle. Changes to the direction, architecture, components, services used, etc. really make documenting code not worth it. Complete re-writes wouldn't be uncommon producing unnecessary work.

     Documenting code libraries like I've owned/developed/managed in the past is a polar opposite. The code has to written to be intuitive & reusable to its destined audience. Because of this, it's a requirement that documentation is clear, concise and includes examples or working demos. Following prior architecture & code patterns are helpful too to train staff on its usage adopt it into their workflows quickly. 

    Just because documenting code for application is difficult because of change doesn't get it off the hook entirely. Where applications need documentation is anyone who needs to use the finished product for its designed purpose.

"The Sprint team created a great demo, isn't that enough?" 

     That demo for the finished product after the sprint isn't enough. It merely illustrates to those who showed up to the demo; mainly stakeholders, product owners/managers and the sprint team themselves. Once this application is in the wild there are more groups involved than just the ones involved in dev. Some examples of those groups could be

  • Business Operations
  • Business QA
  • Deployment Team
  • Sales
  • External Clients

     Each one of these groups I named will require a different type of documentation. Some require training manuals, quick reference sheets, or a help system. The rule of thumb I like to use to start writing documentation for an application is when the business logic is established. Code or the UI/UX can change but the business logic rarely if ever does. Then as everything nears a final state the smaller details like the GUI become very minuscule details to add later.

No matter how good the application is, if no one is aware of its uses, knows how to use it, or can get support using it, it's a failure.