Documentation is communication. How to communicate to succeed with your community?

This presentation consists of three major parts:

- Why to document (15 min)

- What types of documentations exist (15 min)

- What tools can be used to simplify the process  (15 min)

Why to document

What distinguishes successful and sustainable projects from those that disappeared in void? Spoiler: community. 

Community is basically what drives the project. And documentation is an important part of a community builder. Of course, unless you have some very small and obvious project which may not require any documentation. Whatsoever, how many small and obvious projects do you know? What are the chances your project will fall into this category? 

Documentation is a visit card of your project. Via documentation you bring a message to your clients or community. It is a way of communication. And without communication there is no sustainability, consistency, etc. If there is no information about the project, you even don’t know whom to ask sometimes.

The important message here is that it is very easy to fall into the “obvious” trap, e.g. “it is obvious for me -> it is obvious for everyone”. Documentation helps to avoid that trap by simply looking onto things from different perspectives.

Documentation within a group or a company may also be a single source of truth. 

Documenting processes and protocols may be even more important than documenting your project itself, especially if it is some kind of a library.

Finally, documentation per se can be a product. For example:  https://www.baeldung.com/ or https://mkyong.com/java/

Types of documentations

There are different ways of how to communicate and present information:

- software code itself;

- diagrams/ graphs;

- mind maps;

- text (fine solution in describing diagrams or case scenarios but in general not the best solution nowadays. Do you read much?);

- videos.

From another perspective there is a high level overview and a low level overview of the project.

High level overview:

- user documentation ( for those who will use or are already using your products);

- use-case scenarios;

- architecture overview (for those who plan your project's future).

Low level overview:

- automatic documentation based on tags in code;

- documentation of code features;

- issues/bugs tracking.

There is another perspective in terms of time: do you start a new project or do you try to deal with an existing one? These are two different strategies. 

If you have just started your project – make it a routine for you or your employees to document, make it one of the processes for your developers. Allocate enough resources. For a big project a good documentation requires about 1:1 resources allocation, e.g. 1 hr development = 1 hr documentation.

For an existing project the best case scenario is to find a person who understands and knows what is going on. If there is no such person, and that’s usually the case, allocate a role to do this job: analyze the project, gather information from managers, talk to solutions architects, developers and so on. Reasoning here: at least someone should start ding this! Once the initial skeleton is done, create or integrate making changes to it into the existing continuous delivery pipeline .

Important! Documentation per se is a project. This means the same processes as in software development: analysis; requirements capture; design; implementation; maintenance.

Ultimately, before doing any documentation determine your:

- Focus groups: developers; integrators; administrators; end users; sales; operations; executives;

- Level of expertise: beginner; middle; advanced;

- Level of details: high level overviews and big pictures VS very technically detailed;

- Journeys and entry points: How to…; What if…; Why…

That helps greatly in structuring information you want to communicate via documentation and also defines clear metrics on what has to be in your documentation and in what places. Weight the importance of nodes and focus on the important ones.

The next part covers a wide range of tools one can use to create documentation.

Tools 

The biggest issue in creating documentation is that your team doesn't know how to do it. If you make the process understandable and a standard one, there will be no problem.

I will give you an example of how to describe a routine process for creating documentation in a software development team.

Here are some tools (with examples given in my presentation) for the types of documentation we have previously covered:

- Javadoc and co (analogous tools for different languages, e.g. Doxygen, JsDoc, etc.) - embedded documentation snippets, useful for small libraries;

- Restructured/Markdown - file format and processing engine. Good to cover large or non-code related documentations;

- ReadTheDocs - docs hosting and processing; can be attached to public GitHub/GitLab/Bitbucket repositories;

- GitHub actions (or any CI/CD pipeline engine) - make sure to continuously deliver your application;

- Miro; LibreOffice Draw; Figma; Notion; … - for your diagrams/ graphs, mind-maps.

Some handy utils for screencast:

- Peek - command line interface utility for gif recording;

- Vokoscreen - mouse clicks and screen capture.