Taking the Pain out of Documentation

Documenting code in parallel to your development can be the solution to the dreaded documentation phase

By Lauren Matura, BreakFree Solutions Senior Solutions Engineer


You have just finished developing your code. Now you must finish the documentation before you can release. If you’re like most technical professionals, this is a dreaded task (hence why it was left for last). But what if I told you that documenting could be made easier by working it in parallel to your development?


As a Senior Solutions Engineer at BreakFree, I have been on many product teams in my career. Trust me — you are not alone in despising the creation of technical documentation. Most of the people that I have worked with share this sentiment.


Documentation is usually an afterthought when developing a product; and therefore, it is generally rushed to meet deadlines and ends up lacking in quality. By beginning documentation earlier in the process, the documentation itself can be improved.


Documentation should be started as soon as development, if not before. By starting documentation early, you allow the opportunity for it to be utilized early on for knowledge transfer between teammates. This enables easier cross-training as well as more eyes on the documentation to increase the quality.


Documentation should be a living and malleable format until the product is released. As changes are made to the product, the documentation should be updated in tandem. Making updates as work progresses allows the documentation to be tackled in smaller portions.

In addition, no one person should be solely responsible for documentation; it should be a shared responsibility of the entire team. By limiting documenting to one person, it discourages cross-training and knowledge transfers. Additionally, documentation is much less of a daunting task when you are not solely responsible for the whole product.


One way to assist in this is to develop a template as a team as part of the project plan and make each person responsible for filling in a section of the template. Each section should then be peer reviewed for increased clarity. Product documentation should also be tested just like your code!


In summary, if you follow the below tips for quality documentation, you will increase the quality and reliability of your documentation (as well as make it less dreaded).


  • Treat it as a product deliverable (because it is one)

  • Start early

  • Develop a template

  • Share the responsibility

  • Test and peer review



Do you have questions on the documentation process? Leave a comment or reach out and we'll help you find the solution.




53 views0 comments

Recent Posts

See All

Empower your platform team with safe and effective experience By Bradley Clerkin, BreakFree Solutions CTO At BreakFree, we build awesome platform products for developers and data individuals. However,