This chapter is from the book
This chapter is from the book
This chapter is from the book
This chapter is from the book
Keys to Success
The keys to success are simple:
- Decide—Determine what you need to document for your project and when it makes the most sense to produce that documentation. Some things, such as code comments, are easy to time. Other items, such as threat models, are more difficult. Work as a team with your product owner to determine the must-have documents at each stage of your project.
- Commit—Once you have a documentation plan, stick to it. Put it in your definition of done. Hold yourselves accountable. Documentation is never fun, even when it’s broken into small chunks. Remind your team that a little bit of pain will eliminate a great deal of risk come release time.
- Communicate—If this is the first project to move forward without extensive up-front documentation, people will be nervous. Help them out, especially at the beginning of the project, by sending frequent updates, pictures of whiteboards, and any other documents that are produced. Do like your math teacher always told you and show your work. Seeing working software and physical artifacts goes a long way toward calming the fears of even the most anxious executives.
- Invest in automation—Documentation is easier and ultimately cheaper if you invest a little time in automating either the system or the documentation itself. For example, if you can create an automated script to compile all the code comments and parse them into documentation, you’ve saved a manual step and instantly made your documentation more in sync with the actual code. It’s also much easier to document acceptance test results and API documents automatically than it would be to do manually. On the flip side, you might find that automating the features themselves can save you a lot of documentation work. For example, a manual installation process might require a 40-page installation guide; an automated installation process, on the other hand, probably only needs a one-page guide and is better for the end user as well. Whenever possible, automate either your documentation or the features it supports. The results are well worth the investment.
Being agile does not equate to no documentation; it means doing timely, accurate, responsible documentation. Make sure that documentation is equally represented in your team’s definition of done alongside things like code and automation. Remember that when change happens, it’s not just the code that changes—the entire software package that you are delivering changes, documentation included. Lastly remember that as much as you might wish otherwise, documentation is a part of every software project. When you do a little at a time and automate as much as possible, you’ll find that while it’s still an obligation, it’s not nearly as much of a chore.