Home Documentation system

Documentation system

Introduction

The documentation we provide falls into 2 main categories.

Client documentation

This is product documentation for our clients (and sometimes their clients).

We create client documentation for most B2Broker products. Usually, it contains Release notes, User and Administrator guides, API description and other product-specific documents.

The client documentation is updated for releases and verified not only by technical writers, but also by product managers, analysts, developers, whoever.

For each product we launch a documentation website. In fact, there are usually 2 sites: test and production. We use the test site for documentation approval and checking, and it is accessible only via B2Broker VPN. The production site is an “official” one and is available for everyone on the Internet. When you merge your changes they are usually deployed to the test site first before before being moved to the production.

On our Jira board you can find Epics for each documentation project (== B2Broker products). In each Epic you can find all the required information to navigate the product:

  • Repo URL

  • Test and production sites URLs

  • Product staging where you can try it yourself, and so on

You can also find an up-to-date and complete list of all our documentation sites on this page.

Internal documentation

It’s the documentation for internal use which, in turn, is divided into smaller categories:

  • TW documentation: everything related to technical writing at B2Broker and our team, including style guides, processes, tools, etc. All of these are stored on this site. Should you have any ideas, don’t hesitate to contribute!

  • Process documentation: processes and procedures for interacting with other departments and teams: how to create a task, how to initiate the process of creating documentation for a new product, how and when to notify us about an upcoming release, etc. As well as team roadmaps, reports and other bureaucratic stuff. It is stored in PMD Confluence.

Note

Currently we don’t provide any type of internal product documentation and specifications.

With the exception of the Process documentation, which is rarely updated and doesn’t require any specific explanations, we adhere to the same approach and flow for all other documentation categories.

And that’s what we’ll cover in this article.

Our approach

We follow the Docs-as-Code approach for our documentation. This means that we use the same tools and procedures as developers use when creating their code.

Namely:

  • We use reStructuredText lightweight markup language to write our docs.

  • We use Visual Studio Code to work on our source files.

  • We use Git for collaborative work.

  • We store our docs in GitLab repositories.

  • We use a branching strategy which is based on GitFlow.

  • We use Sphinx static site generator to turn our source files into HTML pages.

Documentation system

DocFlow

Below is a brief description of a regular procedure of working on client documentation. To learn more, refer to Jira workflow.

Step 1. Start working on a task

Working on a task starts when a Technical Writer moves it to IN PROGRESS. The tasks are taken from TO DO/BACKLOG according to their priority and considering the specified “Due date”.

After that the Technical Writer branches out a new feature branch from develop. We usually name a feature branch after its corresponding ticket number in Jira, for example: tw-111.

Step 2. Working on a task

During the work, the Technical Writer updates source files.

After the work is finished, the Technical Writer creates a request to merge their feature branch with develop and submits it for peer-review. The process of creating a Merge Request is described here: Merge requests 101. The Technical Writer links the Merge Request to the task and moves it to FOR REVIEW, a notification about this is sent to the #techwriters channel in Slack.

Step 3. Peer-review

At this step, a Reviewer — usually another Technical Writer — proofreads the docs in the Merge Request and checks it for:

  • typos

  • comprehensibility and readability

  • unambiguity

  • compliance with our Global style guide

Peer-review starts when the task is moved to IN REVIEW, and ends when it is moved to FOR ACCEPTANCE.

Step 4. Acceptance

At this step, an Accepter — usually the Lead Technical Writer — evaluates the quality of the docs in the Merge Request, taking into account other documents and projects of the company. Namely:

  • uniformity and consistency of terms and styles — across all projects

  • unambiguity — in terms of other projects

  • coherence

  • structuring

  • markup

Acceptance process starts when the task is moved to IN ACCEPTANCE, and ends when it is moved to ACCEPTED. After that the Technical Writer merges the Merge Request, and fills in the Solution filed of the task with links to a test sites.

Step 5. Approval

At this step, an Approver — usually a product stakeholder: Product Manager, Business or System Analyst, Developer — validates the pages mentioned in the Solution field and checks it for

  • correctness

  • completeness

  • sufficiency

in terms of business and target audience needs.

Once the task is approved, the Approver moves it to FOR DEPLOY.

Step 6. Deploy

At this step, the Lead Technical Writer publishes the new version of documentation to the production, merging the develop and master branches.

After that the Lead Technical Writer moves the task to DONE, the work is completed.

#onboarding