Don't Underestimate Documentation

Documentation Sounds Like an Annoying, Boring Thing

Maybe you feel that documenting the project or your code is an extra annoying step. Often, documentation for projects is outdated and irrelevant. In such cases, most of the expertise is hidden in analysts or just developers. In this article I'll try to explain why having a good documentation culture will make projects much more stable and successful.

Writing Good Documentation Often Makes a Big Difference

There is no specific rule on how to make perfect documentation, but obviously plain text without details is much worse than documentation with screenshots, diagrams, and images. It takes time to write a quality manual, but it's worth it because it solves many problems at once, including slow onboarding processes, slow communication, single-person projects, and lack of team support. 

Onboarding Process Improvement

Often when documentation is outdated or doesn't exist, new employees have to ask too many silly questions and waste senior players' time. In the case of rich documentation, new devs will learn the vast majority of the project logic all alone. Also, the process of learning the project will be shortened and new employers won't be that dependent on the existing team

Faster Communication 

Having well-documented features means you don't need to explain the same thing again and again — all you have to do is give a link to the documentation. Also, the document itself might be a good place for discussion or a place for potential improvements.

Removing the Single Person Project Curse

Have you ever seen a project that is mainly maintained by one person? Then you might have seen how their project dies when they leave the company. The best way to avoid such scenarios is to ask this person to document the project from A to Z. Unfortunately, such situations are intentionally created, and such "one-person projects" have no documentation because this one person wants everyone to depend on them. Forcing them to make documentation will solve this problem and remove the risk.

A Support Team Means a Stressless Life

In cases when production is supported by a dedicated team, proper up-to-date documentation might be priceless. For a production issue, the support team might fix the problem without waiting for the development team.

Create a Workshop to Share Documentation About Your Feature

After each sprint/iteration, it's very useful not just to share how your feature works but also to show how it works by providing a recently created manual. Having such practices, a team will:

• Build a proper documentation culture
• Make documentation standardized
• Be assured that all new features are well covered by the documentation

Sady, such practices almost don't exist in real life, but I would recommend integrating such events. You'll see that the confidence of each team player will grow. 

Obvious Documentation Recommendations

In order to keep documentation readable and maintainable, please follow these instructions:

• Provide more screenshots and images
• Make more diagrams (for example, draw.io)
• Keep it simple and easy to read like you've been doing for yourself
• Follow the same style convention

Where to Keep Documentation 

If we are talking about documenting source code, there are two ways to store documentation:

• Rich README file right inside the project (became more and more popular because it reduces the distance between developer and documentation)
• Confluence pages or any other documentation framework. This option is more useful especially when the team has not only developers but testers and analysts. 

Personally, I prefer any web pages instead of some README.md files because webpages are much more flexible and have more potential features.

Documentation Tools

Depending on the project, there are many tools that can be used. Some general tools that I recommend include:

• draw.io has many features that allow you to picture your project with its dependencies. 
• Markdown is a format that allows you to make your README files much more visible.
• Confluence is a paid but popular solution for documenting anything. It integrates with many tools including draw.io. For small teams, it is very affordable.

If we talk about code tools specifically for code documenting then next tools can be used:

• JavaDocs generator from IDEA
• The REST API generator Swagger. Swagger allows you to generate documentation and live examples for each API call. This tool is a "must-have" and became the enterprise development standard
• The REST API generator from Spring. It's also a Swagger version but embedded right inside Spring Framework
• Docs generator for GRPC protocol
• Class visualizer, which shows images with class structure. Such a tool would be used by developers and no one else. Just simplify the process of reading the code.

If these aren't what you're looking for, here are some alternative documentation writing tools.

Self-Documented Code: Alternative to Documentation?

Maybe you have heard about such things as self-documented code. What is it? Well, it's a set of conventions and rules for how code has to be written. For example:

• All classes have to start with a capital letter. For example, User
• All final content fields have to be written in capital letters with an underscore between words. For example, THIS_IS_THE_FINAL_VARIABLE
• All variables have to start with lowercase and be in camel case. For example, usersDetailsVariable

Well, does it actually document anything? No. It's a different thing, but in general, code conventions lead to code visibility and make it much easier to read. So in some sense, self-documentation solves the same problems as simple documentation.

Who Has to Write Documentation?  

Everyone has to write documentation and clarify moments related to their own functionality. Developers can explain what code is responsible for which feature. Managers can explain business aspects. Web designers can clarify UX importance moments. But in practice and in most cases, developers are too lazy to document anything and avoid it. So analysts and managers are doing that job quite often. But analysts or managers can't document code-related things and, in the end, such documentation is not usable for developers. So as a result, such documentation is useful only for analysts and managers. 

The Final Message: Documentation Is Important

Well, there is not much to add. I hope I've provided why you better write good documentation and keep it up to date. This is a lesson I learned while working on many projects for more than ten years. Especially in big and slow companies, missing documentation will cost a lot from a time and performance perspective. So, having a habit to write docs about the feature you have implemented will help you and everyone on the team.