MS Word regularly gives us “surprises”: “moved” screenshots, “floating” tables, blank pages when printing. This article is about how we were looking for a replacement for MS Word (and actually didn’t find), but found an opportunity to improve our documentation process globally.

At App Soft, we make high-tech tools a serial product. The company mainly operates in the B2G (business-to-government) and B2C (business-to-client) sectors.

With documents in the B2C sector, there is freedom to choose the format, name and content of the documentation. In the B2G sector, about 70% of the documentation that we develop should be prepared in accordance with the requirements of the government and submitted for approval to the customer in the DOCX format.

We transmit to the user all the operational documentation in printed form, so all documents are ready-to-print. Our documents have two target formats: DOCX and PDF.

For the implementation of our tasks, the department has traditionally used MS Word for many years.

With each new editing of a document compiled in MS Word, in about half the cases screenshots “slide out”, tables with icons “float”, and when a document is printed, appear invisible blank pages. These document layout operations take away from the author not only time, but also the desire for creativity – development of new documents.

During the next search for invisible blank pages in a DOCX document in our department, came up the idea to try a new documentation development tool. We wanted to reduce the time for layout and preprint preparation of the document.

As a result, we were not able to completely get away from using MS Word, but in the search process we built a new scheme for working with documentation.

Next, I will try to tell you which tools for working with documents we considered, why we settled on Confluence as a result, what problems we encountered and how we were able to solve them.

Tool selection

We read articles about existing documentation development tools and talked with colleagues from other companies. The following tools seemed most suitable to us:

  • Dita
  • DocBook XML
  • Confluence

The first two tools didn’t fit for the same reason: we needed programming skills that we did not have, and to create a new document template we would have to call for the help of a programmer. The transition to work with them, according to our ideas, would take about six months, possibly more. Due to the above disadvantages, we decided to abandon the full testing of these tools.

Confluence from the very beginning made us happy with WYSIWYG-editor. On average, technical writers took about a week to master the tool, layout of documents “not in accordance with government standards” was made easier.

In B2G projects, PDF is important to us as a format for user documentation. Therefore, we immediately installed the appropriate plug-in for Confluence – Scroll PDF Exporter. With it, we tried to create custom templates with the necessary parameters. We were satisfied with the test results: we made out one of the documents with a large number of screenshots and graphic elements in MS Word for about a week; in Confluence, we managed to lay out the same document in 2 days and achieve a better visual presentation.

We also tried to configure the template for Scroll Word Exporter in such a way as to get a document specified for all the rules needed. After two days of reading the Confluence and Scroll PDF Exporter handbooks and trying to customize the current technical specifications template, we realized that this tool is not suitable for the development of documents executed in accordance with the requirements of B2G.

So, for example, we were unable to make numbered non-bold headings of the second level so that the text was not a heading, but a paragraph. I had to manually write the paragraph number and use the paragraph style. It was impossible to arrange bulleted lists with dashes (only circles, squares), numbered lists were drawn without a dot and alphabetical lists – only with Latin letters. Paragraph’s spacing was adjusted only manually.

A few months after we began to study Confluence, the developers of the tool implemented the function of editing documents in their original format. This allowed us to store our “guest” documents and create new documents that do not require strict execution in the same place. MS Word files are stored in Confluence as attachments, for editing they are opened and saved in MS Word on the user’s PC, and when saved, the new version is automatically uploaded to the Confluence.

So we got the idea to use Confluence as a tool that would solve three problems:

  • Creating a knowledge base.
  • Development, storage and updating of documentation made not according to standards.
  • Storage and updating of documentation developed in accordance to standards.

Potential of Confluence

Our expectations from the Confluence functionality were not fully met, but after testing was completed, we had a generally positive attitude towards this tool. Below we formulated its main advantages for our department:

  • Customize and support the tool on your own.
  • Easy to learn.
  • The ability to organize a knowledge base about company products and store all compiled documentation in DOCX and PDF in one place.
  • Support for documents versioning.
  • Ability to use single source technology.
  • The possibility of joint work of developers and technical writers on documents.
  • Storage of working documents and information in one place.
  • The ability to develop documents at anytime from anywhere in the world.