Ready, attention, patch! How to Implement Online Documentation for Cumulative Changes

Hello readers! My name is Vladimir Markiev, but today call me Alexander Sergeevich, I am a technical writer at Docsvision. When we created the Docsvision online documentation using Antora, we were faced with the task of leaving a place where the list of cumulative changes would be integrated in the future.

The right moment for integration came after we prepared the documentation site for release. This work turned into an interesting experience of intra-team interaction, which I will share today.

Task in the studio!

Cumulative changes are when, after the release of a product, fixes are released for it upon request through technical support. The client leaves a request for correction, the developer corrects the code, makes a commit, adds a message. This is the message we have chosen to display in the list of cumulative changes.

The requirement sounded like “the page should be part of the site, look organic and be integrated into the build process.” How many IT people do you need to fulfill the requirement? Exactly three: one technical writer, one designer and one configuration engineer.

The three of us consulted, discussed the requirements, made a plan. The technical writer (that is, me) builds the page using Antora. This is logical because I write documentation in AsciiDoc format, which is converted to HTML using the Antora static site generator. The assembly of the site and cumulative updates is configured through TeamCity, so the assembly of the page will be performed through TeamCity. The page and the list of changes that comes to it should be designed according to beauty.

This poses a challenge for each participant:

  • The task of a technical writer is to add a page along with resources to the site.

  • The task of the designer is to design the frontend of the page: styles, search, grouping by category of changes.

  • The configuration engineer’s job is to set up TeamCity to support building the site, building the patches, and adding the list of changes to the site at the same time.

Embedding but not mixing is a task for the technical writer

My task is to add a page to the site, that is, you need to:

  • Create page

  • Make it as neutral as possible

  • Display on site

Page in the navigation tree
Page in the navigation tree

The task is clear, I add an empty page, and in it an attribute and a title:

:page-layout: patches
= Накопительные обновления

One page is not enough, it requires exclusive scripts and styles. Exclusivity defines an attribute that tells Antora to use a special page template. The template itself will not appear, it also needs to be created.

I took as a basis the standard template from the repository user interface Antora and created a special one based on it.

added to <head> this page, two new lines for the style and for the script:

<link rel="stylesheet" href="https://habr.com/ru/post/712298/{{{uiRootPath}}}/css/vendor/patches.min.css">
<script type="module" crossorigin src="https://habr.com/ru/post/712298/{{uiRootPath}}/js/vendor/patches.min.js"></script>

Styles will set the external sid of the page, and JavaScript will access the database for a list of cumulative changes and add them to the page. This is what our designer did.

Forward to the front!

Browser search at work
Browser search at work

The task for the designer was set as follows:

  • Apply end-to-end change search

  • Create a friendly interface, clear and convenient tree structure for the page

  • Of course, solve the problem in a short time

Pass-through search is implemented thanks to Vue 3 for generating and displaying HTML on the page. The framework allowed to search for changes on the page directly from the browser, without requests to the server.

The designer implemented a friendly interface using Quasar. The ready-made Vue components provided by the framework, such as pop-up panels, input fields, buttons, icons, also made it possible to solve the problem in a short time.

The main difficulty is to create a tree structure by converting a flat list from the server into a tree structure, the changes on the page must be grouped by release and patch type.

For this task, the designer used TypeScript: convert the data into an array of releases, consisting of child arrays, put errors, optimizations, functional and other cumulative changes into the arrays.

Thanks to Vite.js for building the project.

The resulting code had to be tried on seven times. I also had to cut off extra lines in the script or conflicting styles in CSS seven times too. A separate type of entertainment is a game of detectives to identify interfering lines. Classic.

Beautiful tree structure of the page
Beautiful tree structure of the page

Speaking of the server

The server part was taken over by our configuration engineer. Configuration Engineer Responsibilities:

  • Create a Service to Store Changes

  • Add Change Description Editor

  • Set up project build configuration

Cumulative changes are stored in the database, and from it they get to the site page, which is indistinguishable in appearance from other pages.

List of changes included in the commit
List of changes included in the commit

The service stores information in a SQLite database. Changes get into the database when the developer makes a commit to the repository. This starts the build of the product in TeamCity. TeamCity sends a POST request, in the body of which it passes the product ID, build ID, version, and an array of included changes. If a build is published to the Support Portal, the service will include changes to previous builds that were not published to the Support Portal. Information from the request will later get into the container service and into the database.

Example of information received from TeamCity:

{
  "Id": 117188,
  "ProductId": 1,
  "FileVersion": "5.5.5957.327",
  "Changes": [
    {
      "Title": "ERR-2471",
      "Description": "Диалог атрибутивного поиска. Заменить кебаб на крестик",
      "Type": 1
    },
  ]
}

What is written with a pen can be changed in the editor

The information in the database is not set in stone, if a commit has a too jargon message, it can be edited through a special editor.

The editor allows you to select the type of change, edit the description, or make the change purely informative – transfer it to notes and not display it on the site. The editor is the last step in development, then it only remained to automate the assembly of the project.

Assembly chain

Configuration chain
Configuration chain

The engineer created a documentation build chain of 5 configurations:

  • Composite – starts the build chain, checks for changes in the documentation repositories.

  • Patches – collects styles and scripts for the page with a list of cumulative changes.

  • UI bundle – collects the user interface of the site, takes resources from Patches.

  • playbook – assembles the site using Patches and UI bundle.

  • Deployment – updates the site, replaces the container with nginx.

At startup, changes in previous configurations of the chain are checked, if any of them can not be collected again, it will not be collected.

After automation, we released the created page to the online documentation, where it is now convenient for everyone to see the list of cumulative changes.

Conclusion

Thus, the latest documentation appears on the site, which includes a main section and a section describing cumulative changes. If there is a need to change something in the site or documentation, then the changes will appear on the site within 10 minutes after the commit.

The experience of collaboration of a technical writer, designer and configuration engineer within the same task is definitely a significant contribution to strengthening team interaction.

Similar Posts

Leave a Reply