Documentation Culture

Photo by Lucia Macedo on Unsplash

TL;DR

Write your documentation using Markdown notation for clarity. Track and share your work with colleagues for feedback. Keep documents and presentation decks in the same place as your code for a neat and organized project.

Introduction

We are all familiar with the term Tech Debt.

Today I want to introduce a new one — Chapter Debt.

As a Chapter, we know about a lot of good practices, and we understand they’re beneficial.

However, we either don’t use them or only use them a bit.

• 01 — DOCUMENTATION CULTURE
• 02 — Testing Culture
• 03 — Coding Style Culture
• 04 — Code Review Culture
• 05 — Competence Culture
• 06 — Hiring Culture

This is the first part of a series talking about Chapter Debt: “Documentation Culture”.

Background

We need a better technical documentation culture and the culture should be pervasive.

Alone Together

In big organisations we work alone and together at the same time, a lot of our findings get lost and go unnoticed, often we in different teams (or squads if you like) do the same thing in different ways or in the same way, but we even don’t realise it.

Random Order

What’s the issue with the current documentation?

If exists, located in different places, namely:

• In the code repositories (e.g. a large readme.md file, which is not readable and contains a lot of different information)
• In the Confluence-like document management system in various chaotic sections. It is incomplete and inconsistent, containing fragments of information.
• Documentation can also be found on a business communications platform (e.g. MS Teams), which adds to the confusion.

Definitely Undecided

Even if we wrote something well once, there are no rules for updating it if there are changes.

I believe that the problem of lack of quality documentation is not that we have nowhere to write it, but the lack of common rules and understanding of why to write it, how to write it and how to make colleagues aware of these changes.

Framework

3 clear steps

Documentation enhances awareness when choosing technology, allowing you to record why a particular choice was made.

Presenting technology in a workshop ensures that you are convinced it’s the right choice and undergo a review from colleagues.

Toolkit

This article adds more details to what we talked about before. It might help you understand the information better.

Let’s build the examples in our article on top of the Azure DevOps.

Squad Project

The refinement phase in the Squad project identifies the documentation work that needs to be done. After creating the Dependent Task with a relationship link from the original User Story, it must be added to the Chapter project.

Chapter Project

The primary objective of the chapter is knowledge sharing. This project serves as a centralized “knowledge-sharing factory”, focusing on collaborative work on documentation and presentations.

The “Documentation” board functions as a tool to track and measure knowledge sharing within the chapter. Its purpose is to provide a constant overview of ongoing documentation efforts. The board emphasizes consistency and transparency, grouping projects using swimlanes and employing the “Dependent Task” type as the Product Backlog Item (PBI).

Workflow

On the board the ticket goes through five stages:

1. New
2. Wiki
3. Collaborative session [ Workshop / Chapter Catch Up / Engineering Meeting]
4. Public article (optional)
5. Done

Each of the middle three columns contains two states:

• Doing
• Done

However, a Dependent Task type has 3 states:

• New
• In Development
• Done

In this workflow, completion of the wiki writing does not mark the ticket as finished — it remains “In Development” until the corresponding workshop is conducted. Even after the workshop, the status remains “In Development” as the decision on whether to create a public article is pending. If the decision favors writing the article, the ticket transitions to the “Public Article” stage. Otherwise, it is solved, moving to the “Done” state.

The board is unidirectional. Always from left to right:

• Conduct a workshop only after completing the writing of pages in the wiki.
• Write a public article only if it is based on the company’s practical experience.

Now let’s break down each of the 5 states separately.

1. New

Always consult with the business first.

Do not raise any matter without discussing it with the PM and the team.

Avoid elaborating on the task since the ultimate result will be documentation. Instead, utilize a template:

Type of wiki:

• New
• Rewrite existing documentation
• Transfer of an existing feature to a new technique
• Spike

Type of presentation:

• Workshop
• Chapter Catch Up
• Engineering Meeting

Links:

• Wiki (required)
• Presentation (required)
• Public article (optional)

2. Wiki

This represents the implementation of the LEARN direction. The article should be written using Markdown notation. Each wiki page is required to include a link to a ticket where subsequent comments can be appended, along with acknowledgment of the author. Work on an article begins in a feature branch. After the article is ready, the person responsible for the article ticket (author) creates a pull request, mentioning individuals or teams for whom this information is essential. Once approved, this article is merged into the repository following the team’s approved process.

3. Collaborative session

This represents the implementation of the SYNC direction, comprising three distinct types: Workshop, Chapter Catch Up, and Engineering Meeting. These types are differentiated based on their intended audience coverage.

Workshop

• Frequency: when necessary.
• Responsible: The ticket assignee is responsible for organizing the workshop.

Chapter Catch Up

• Frequency: bi-weekly.
• Responsible: The chapter lead is responsible for organizing the chapter catch-up.

Engineering Meeting

• Frequency: once a month
• Responsible: The Chief Technology Officer (CTO) is responsible for organising the engineering meeting.

The presentation for Collaborative session, it is a summary of the article. There is no need to invent anything: write the wiki article first, then create a presentation based on it and refer to the wiki article.

The idea that everything is generated automatically following the principle of presentation as code without extra efforts.

The session is recorded using Business Communication Platform (e.g. Microsoft Teams), then the responsible person disables auto-delete and includes it in the wiki documentation.

The outcome of your presentation will be a page in the meeting notes section of wiki with the following structure:

• Date of the presentation
• Link to the wiki
• Presentation (in markdown format, named deck.md)
• Embedded video recording

4. Public article

This represents the implementation of the HIRE direction.

Prospective candidates frequently conduct research on the company prior to job interviews.

This scenario exemplifies a win-win situation. A personal account serves as an individual brand. Publishing an article on platforms like Medium not only enhances the personal brand but also contributes to the public image of the company.

IMPORTANT: Sensitive information must not be disclosed.

Therefore, articles undergo an editorial review to ensure compliance with this policy.

Write an article only if it is relevant to internal work, as articles should always be grounded in internal projects. If the content pertains to something else, it is more suitable for personal publication rather than the group associated with the company.

5. Definitions of Done:

1. Wiki article is written.
2. Wiki article is submitted to the repository.
3. Article is available in the Backstage (about this a little later).
4. A collaborative session has been conducted.
5. The presence of the article in a public blog is an optional consideration.

Single Point of Access

The solution puts this plan into action. The Backstage Portal is like an aggregator, kind of like a super organized list. Think of it as a really detailed phone book. Basically, it’s a reliable source that keeps everything in order, giving you both the big picture and all the tiny details.

You can also see it as a way to answer two main questions: “what?” and “how?” In simple terms, it gathers all the needed info from the chapter and squad places and shows it in one portal.

Team-FrontEnd git repository:
catalog-info.yaml file > to register the Team-FrontEnd in Backstage
mkdocs.yml file > to index the Team-FrontEnd documentation
docs folder > with N md files for the Team-FrontEnd documentation
e.g.
AUTH UI
ERP UI
CRM UI

Team-ERP git repository
catalog-info.yaml file > to register the Squad in Backstage
mkdocs.yml file > to index the Squad documentation
docs folder > with N md files for the Squad documentation
e.g.
Ways of working
Strategy
Meeting notes

Another option is to utilize Azure DevOps Wiki or Docusaurus for deploying a UI layout for your documentation, built on top of your markdown files.

Tips

Image created by Author using DALL·E 3

• Consider the feelings and experiences of the developers who will be using your solution. Put yourself in their shoes and try to understand their needs, challenges, and perspectives. This empathy can guide you in creating a more user-friendly and effective solution, enhancing the overall experience for your fellow developers.
• Be precise in your naming and expressions. If you are referring to component libraries, include “Components” in the name.
• When creating documentation for the UI interface, explicitly add “UI” to the title. This is important because it’s related to the UI, and someone looking for backend information won’t find it here. However, be empathetic: include a link to the backend documentation or ask a colleague to create it if it’s missing.
• When you’re working on something, tell others about it quickly. In big teams, someone might have already done it, or they might be working on it too, but you don’t know! Sharing helps you find out if a similar solution exists and keeps everyone updated on your work.
• Instead of having lots of calls, just share a link. This way, you can easily send a link to your documentation or a workshop video whenever someone needs it.
• If you’re short on time, keep it brief. Capture the essentials now, the details can come later.
• Remember, what you’re doing and documenting is not about the past; it’s about future!

Thanks for checking out this article!

If you enjoyed it, please clap, subscribe, and stay tuned for more related content.

See you soon!