My article on Agile Principle #6 provides compelling points on why documents are the best way to communicate to and within a software development team. But how can we create and foster a document-driven communication culture in our engineering organizations?
Define document expectations
Engineers do not like ambiguity so give them clear direction. This means defining what documents are expected and when they should be written. Here are some reference expectations:
- Product requirement documents should be written to communicate product changes to engineers when the functionality cannot be communicated in less than 3 sentences
- Design documents should be written to communicate designs inside of development teams when implementation will take more than a month
- Task breakdowns should be created when there is a chance multiple engineers will collaborate on an implementation
- Launch checklists should be written to prepare large changes for release to end users when the change could impact user trust
- Postmortems should be written after production outages causing monthly Service Level Objectives to be missed
Create document templates
Templates make it easier and quicker to write and review documents. Templates are also repositories for organizational knowledge. Make sure templates are available for all commonly written documents to reduce the barrier to entry.
My Software Engineering Program contains several document templates you may find relevant.
Include documents in performance evaluations
Documents are a great way for members of an organization to demonstrate their value during performance evaluation. By recommending that engineers include documents they wrote during the performance evaluation period in their self-evaluations, you can increase the adoption of document writing.
Commenting on documents is another way engineers can be engaged and add value. It is valuable to include commenting on documents as another performance evaluation input to recognize this important work.
Make documents accessible and searchable
By making documents easy to find and access you can realize the value of documents as documentation. People should not be asking for permission to access documents. People should be able to find relevant documents using keyword searches. Every time someone easily finds useful information in an internal document, the value of the document-driven communication culture is reinforced.
Initiate cultural change through respected engineers
People will not adopt the new practice if the engineers who command the most respect in the organization have not adopted it. Make sure that the official and unofficial internal leadership is excited about the change. Ensure work is lined up that can be communicated through documents in the short term. If there is an entrenched culture it can take time and effort to change so be patient too!
Leave a Reply