“Ink is better than the best memory” – Chinese Proverb
One of the cornerstones of the Agile manifesto is “Working software over comprehensive documentation.” This refers more for customer facing documentation than it does for internal development documentation.
Why is internal development documentation difficult?
Agile and Lean development methodologies prioritize the development of a working product over exhaustive documentation. Continuous release style of development often make the maintenance if internal documentation a moving target for anyone in the company – product managers, engineers, designers and QA alike.
Why do we need documentation if everything keeps changing with every release?
Good internal documentation is required precisely because different parts of the product change with every release. During the initial stages of development of a product, it is easy enough to get by without comprehensive documentation. But later in the life of the product, any changes require careful consideration of dependencies in the back-end as well as the front-end components of the software.
“The dependencies are in the code.” – Developer
What should internal development documentation look like?
At RightScale, we worked on an agile weekly release cycle on a product that was always being improved upon. While the company wiki had engineering and product specs pages, there was very little design documentation that reflected what the current system looked like, and how it evolved to be the way it is.
I implemented a documentation style in the company wiki that focused on the following features:
- Organized
The documentation reflects the organizational schema of various parts of the product, how they relate to each other, and then drills down into details as required. For this I used a DoGo map to chart the entire software and it’s dependencies. This hybrid of information architecture and finite state machine is an under appreciated tool that the rest of the team and me have found indispensable for new feature development.
- Modular
Inspired by Brad Frost’s Atomic Design Principles, the documentation system I implemented in RightScale provided many benefits
Every part of the design has it’s own documentation page linked from and to it’s parent page. - High level designs and feature specific designs as well as microinteractions for user interactions each had their own place in the documentation. This avoided a lot of confusion.
- Different parts of the documentation that represented features and UI elements could be updated in sync with the release of changes to the product itself.
- By using a color code, the documentation distinguished between features that are in design, in development, and in the released product.
- Organization of design assets (like wire frames, prototypes, meeting notes, usability study reports), product and engineering specs, as well as development story tickets from JIRA made the development process more efficient.
- Every part of the design had a unique serial number that made referring to it in written communication much easier.
- Cross-linking reused features and designs in the documentation made sure that the developers were implementing a standard design across the product, and it is easy to identify all parts of the product that would get affected by changes to any design.
- Comprehensive
The documentation system I implemented is as detailed or as general as required. All relevant information is presented at an appropriate level in the hierarchy of the design.
This makes this documentation system a resource not just for the design team, but also for Engineering, QA, and Product Management teams. - Timeless
The documentation style I implemented is easy to maintain, and can be scaled up as much as needed as a software product grows and becomes more complex.
To see a sample page of my documentation at RightScale, please take a look here: http://bit.ly/2N5OArf
What benefits were realized?
Implementation of this documentation system showed immediate benefits, first in the design team, and then in other teams as well.
- Sped up the design and development process
- Gave everyone in the company more visibility into the design of the product
- Employees in different parts of the company could contribute their own insight and feedback for the design.
- Collaboration with remote employees was immensely easier as every feature and design had it’s own page in the company wiki, that could be directly linked and referred to by the serial number on the page in any written communication.
- Feature design and development could be paused and resumed with a shorter ramp up time as every detail relating to the design was documented and the team did not have to rely on their memory about what needed to be done.
When everyone from the developers to the product managers are made a part of the design process, everyone starts thinking about their work with a user centered approach, which means a better software product gets released.