.png)
If you ask a Developer if there should be documentation in Agile, they will tell you there are basically two rules:
- Do not talk about Dev Documentation in Agile
- See rule #1.
They will say in Agile Manifesto it clearly states that “Working software over comprehensive documentation”. You can reply that Agile Manifesto also says “Individuals and interactions over processes and tools”, so shouldn’t you be replacing your visual studio (or Eclipse) by “interacting with Pete”. Unfortunately by that time the Developers already closed the door to their cave with a sign “Compiling… Don’t disturb”.
It is very important to have developer documentation. But it needs to be …. what is good word for it … Agile.
Developer Documentation in a nutshell
There are 3 types of developer documentation:
- Code Comments
- Manual documents in shared WIKI
- Living Automated documentation
Code Comments
Writing good code comments is an art. It is common to see code comments done in two ways.
First way is comment overload. Every line of code has 3 lines of comments for it. Most of them are useless, with rare gems. Most devs just learn to white-noise such comments or hide them using tools.
Second way is no comments at all. If code is written clearly, sometimes it is ok to not include comments, but other times you also get “IT IS A TRAP!!!” like this:
There is an old Slavic proverb that is roughly translated to “Code is written once but read 100s of times”. So unless you want to hurt other developers and your future self, the 3rd way is for you: write clean self-documenting code and only use comments in special circumstances.
When writing code, follow the best practices for self-documenting code:
- clear naming
- functions ordering top down for easy reading
- unit tests to help with various edge cases
For other tips, checkout the good ol’ classic from Uncle Bob called Clean Code
In general, comments should be handled with care and only used for special cases such us:
- Providing context why the code is as is with links to a case
- Really complicated logic that can’t be refactored any further
- API or Library documentation which will be publicly visible
Manual Documentation
The manual documents should be kept to a minimum, as it takes a lot for developers to read or write anything that doesn’t compile. It also takes effort and discipline to keep these documents up to date.
A bit of a segway, but I actually think that good developers should be able to write well, since writing clear code is not much different than writing clear and engaging documents on any subject. Writing code is just another way to communicate your ideas. Sometimes you see a piece of amazing code and it is almost as good as reading a book by your favorite author. There is action (10 threads in parallel), horror (exception handling), romance (unit tests passing) and of course great directing.
Here is a list of essential documents that every developer wiki should have:
Tech Stack and Tools
Modern tech companies have been utilizing the micro services approach. It is a good practice to keep technology stack mostly the same across services used in the same product/organization. There are some exceptions, but it is best to have a really good reason for changing the stack, other then trying out some new shiny tech. This document outlines technology and tools that should be used for current and future projects:
Architecture
Each non-trivial application consists of multiple services and integrate with many third party apps. A nice diagram would help to show how services communicate with each other.
Here is a diagram for Uber Services:
This document also gives a bird’s eye view of the main components of the application.
Infrastructure
This document should have a diagram that shows various resources used to host the application on premises or in the cloud.
For example:
Developer Onboarding
Onboarding new developers should be a quick and seamless process. It is a first experience that a developer will have in a new company, so it is important to make it a good experience.
In this document (or wiki page) include all the systems that developers will need to access on the first day and steps to set up a local development environment. Also include a Q & A for common questions that they may have.
Dev Process
Describe a process for developing new features, bugs and hotfixes. Most companies use a GitFlow, but it can vary quite a bit.
Provide definition of DONE. This is when a story or task is considered to be closed and may include a certain level of test coverage, passing of static analysis checks and working E2E tests.
List meetings that developers will need to attend such as Daily Standups for scrum.
Automated Living Documentation
This documentation includes API and BDD documentation which is generated automatically using tools.
In the past we had technical writers that would write piles and piles of documentation on how each class and project worked. That documentation would be stored in special closet and would collect dust for many decades.
Instead, it is much better to keep this type of documentation automatically generated and visible to everyone on a web site.
API Documentation
Use tools like Swagger to generate beautiful and functional API documentation, for both internal and external APIs.
The content will be written by developers directly in the code. It needs to be clear and concise and go through appropriate code review.
A good API documentation makes a huge difference on how many external devs will view your company and if they choose to use your API. It is a also of great help to future devs working in your company to understand how the system works.
Living Documentation
Living documentation has a lot going for it other than a really cool name.
Basically it works something like this:
- When developing new feature, Business Analyst provides some Acceptance Criteria
- Acceptance Criteria is converted to Gherkin Syntax
3. Developer (or QA Engineer) implements Acceptance Tests in code using tool like Cucumber or Specflow
4. On Deployment, acceptance tests are executed. If the tests pass, they are included in auto generated documentation
The generated documentation looks pretty fancy:
It may not have all the details of a manually written document, but unlike manual documentation it is always up up to date, since if any tests fail then deployment will fail. And we can’t have that.
Conclusion
Writing Dev Documentation has been a contentious and controversial topic, but it really shouldn’t be.
Dev Documentation is a major factor in ongoing success of a development team. It facilitates better communication for the current team and provides living history for all the future incarnations of the team.
