As we were looking for a replacement for MS Word, and instead introduced a new document management process
MS Word regularly throws us “surprises”: “moved out” screenshots, “floating” tables, blank pages when printing. This article is about how we were looking for a replacement for MS Word (we didn’t find a spoiler), but found an opportunity to improve our documentation process globally.
At Uniscan Research, we make high-tech products a serial product. The company operates in the B2G (business-to-government) and B2C (business-to-client) sectors.
Our department develops design and user documentation for products being developed, certification documents, marketing materials, office design and decoration (navigation, door signs).
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 ESKD 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 preprinted. 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, invisible blank pages appear all of a sudden. These document layout operations take away from the author of the document not only time, but also the desire to engage in creativity - the development of new documents.
During the next search for invisible blank pages in a DOCX document in our department, the idea came up to try a new documentation development tool. We wanted to reduce the time for layout and prepress 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 what 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.
We read articles on the topic of existing documentation development tools, talked with colleagues from other companies. The following tools seemed most suitable to us:
The first two tools did not 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 pleased WYSIWYG- editor. On average, technical writers took about a week to master the tool, layout of documents "not in accordance with GOST" 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 issued according to all the ESKD rules. 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 ESKD.
So, for example, we were unable to make numbered non-greasy 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. Indentation was adjusted only manually.
A few months after we began to master 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, when edited, they are opened and saved in MS Word on the user's PC, and when saved, the new version is automatically uploaded to Confluence.
So we got the idea to use Confluence as a tool that would simultaneously solve three problems:
Our expectations from the Confluence functionality were not fully met, but after testing was completed, a generally positive attitude towards this tool formed. Below we formulated its main advantages for our department:
To implement Confluence, we selected two specialists from the technical writers department who studied and tested the capabilities of the tool.
For continuous technical support, the system administrators department assigned us one specialist. He quickly responded to technical problems and helped to understand the basic settings of the new tool.
At the same time, we created a working group in the technical writers department, whose task was to plan the data storage structure. The whole structure of our server was divided into categories corresponding to the types of projects of the company. Categories, in turn, were divided into spaces by company products. We also identified a separate category for the internal knowledge base.
When those responsible for testing the systems studied the work in Confluence rather deeply, the stage of mutual training of colleagues began. It took about a month to transfer knowledge to the entire department.
The implementation of Confluence as a whole went quite smoothly, but there were problems.
“I used to do it in MS Word in a couple of seconds. How to do the same in Confluence? ”- we asked ourselves such a question every day during the entire testing period.
So, it was not at all obvious how to align the contents of the table vertically or assign an icon size less than 16 px.
Indeed, the basic set of page formatting functions in the Confluence WYSIWYG editor is significantly inferior to MS Word, however, the functionality can be significantly expanded if you enter the source code editing mode and work directly with HTML code.
We read articles, watched instructional videos on HTML-layout and shared the solutions we found. We created a separate page in Confluence, where we placed useful information on working with this tool.
After the first update of the main Scroll PDF Exporter plugin, 80% of the macros flew off and the page structure went to Confluence. Later it turned out what happened because of the new functionality of the plugin. Throughout the department, we restored the document structure for several days. After that, we made a plan for updating for the future, which we still adhere to:
When the turbulent activity of technical writers and developers finally began to boil in Confluence, the administrator received calls from users of the service. They asked to save them from a mass attack by mail notifications about the actions of other users.
By default, the user only had to go to some page once, after which he was automatically added by the system to the list of observers and received notifications every time this page was changed.
In addition to this, Confluence kindly did weekly newsletters to users listing the most popular Confluence pages. Fortunately, this problem has already been widely covered on the Internet. The solution is to disable the corresponding notifications in the system settings:
Now users receive notifications only if their name is mentioned in the comments on the article.
To test Confluence, we deployed a Windows server. In the initial stages, the server often “crashed”. Part of the problem turned out to be insufficient RAM on the server (recommended size is 11-12 GB). The remaining problems were gone when we turned on the system settings recommended in such cases.
Now the server is working quite stably - disruptions occur about 1 time in 2 months. In the event of a failure, a reboot is sufficient to repair it.
Today in Confluence technical writers, programmers, electronic engineers, QA work together.
We planned to completely abandon MS Word, develop documents exclusively in Confluence and convert them to DOCX and PDF. In reality, it turned out that you can do without the lengthy process of transferring all existing documentation to a new format and then setting up templates in Scroll PDF / Word Exporter. According to our estimates, it would take us about six months to do this. It turned out to be much easier to transfer all developed documents in MS Word format to Confluence and support them there.
We decided not to expect wonderful formatting from Confluence according to all the requirements of ESKD and simply divided all user documents conditionally into documents for the “state customer” and documents for “not the state customer”.
The first we create in the DOCX format, store and update in Confluence. We develop the latter directly in Confluence, export to PDF if necessary.
Thanks to the built-in macros, we use single source technology in user documentation - now we don’t have to manually change one parameter in several versions of documents.
Convenient WYSIWYG-editor makes it easier to make changes to the finished document - screenshots, icons and graphic elements remain in place.
The collaborative editing feature allows you to collaborate on a document. You can share the document with a technical expert directly in Confluence and discuss his comments in real time, and not endlessly spread the document by mail.
To work outside the office, you do not need to configure remote access. To be able to work from home, you only need the Internet.
Confluence offers the user the familiar web page interface with the ability to configure cross-links and open several tabs in the browser for work at once.
Now we store all documents, graphic elements, photos of devices, and we also maintain a knowledge base on company products in one place. There is no need to think about where the source of the pictures or the latest version of the documents can be.
We are currently setting up a process for reconfiguring Confluence pages using the Comala Workflow plugin. However, this plugin does not work with MS Word attachments. We coordinate such documents with the help of version comments. Now we are considering options for setting up automatic approval of DOCX attachments. I want the approval and approval process to be used simultaneously with both Confluence pages and DOCX format attachments.
When we set up automatic approval of attachments, we will try to make a quick conversion from MS Word to PDF. And then - sending documents to our printed products server, from where the printing company takes the documents to print.
We never managed to abandon MS Word, but in the process of finding a replacement, we suddenly found something more. Confluence brought together developers from different departments, formed the company's knowledge base and became the repository of all company documents, regardless of their format.
Our company has a principle: in any incomprehensible situation, make decisions systematically. We believe that a decision that relies on a model is better than one based on expert opinion or intuition.
In the case of Confluence, Eric Rhys's model from The Lean Startup came in handy. In product development, it helps pivot, change the direction of product development. And in the task of finding a replacement for MS Word, try on a new tool more broadly and find related benefits.
We wish fellow technical writers useful models!
At Uniscan Research, we make high-tech products a serial product. The company operates in the B2G (business-to-government) and B2C (business-to-client) sectors.
Our department develops design and user documentation for products being developed, certification documents, marketing materials, office design and decoration (navigation, door signs).
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 ESKD 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 preprinted. 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, invisible blank pages appear all of a sudden. These document layout operations take away from the author of the document not only time, but also the desire to engage in creativity - the development of new documents.
During the next search for invisible blank pages in a DOCX document in our department, the idea came up to try a new documentation development tool. We wanted to reduce the time for layout and prepress 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 what 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 on the topic of existing documentation development tools, talked with colleagues from other companies. The following tools seemed most suitable to us:
- Dita
- DocBook XML
- Confluence
The first two tools did not 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 pleased WYSIWYG- editor. On average, technical writers took about a week to master the tool, layout of documents "not in accordance with GOST" 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 issued according to all the ESKD rules. 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 ESKD.
So, for example, we were unable to make numbered non-greasy 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. Indentation was adjusted only manually.
A few months after we began to master 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, when edited, they are opened and saved in MS Word on the user's PC, and when saved, the new version is automatically uploaded to Confluence.
So we got the idea to use Confluence as a tool that would simultaneously solve three problems:
- Creating a knowledge base.
- Development, storage and updating of documentation developed not according to GOST.
- Storage and updating of documentation developed in accordance with GOST.
Potential confluence
Our expectations from the Confluence functionality were not fully met, but after testing was completed, a generally positive attitude towards this tool formed. 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 versioning documents.
- 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 any time from anywhere in the world.
Implementation
To implement Confluence, we selected two specialists from the technical writers department who studied and tested the capabilities of the tool.
For continuous technical support, the system administrators department assigned us one specialist. He quickly responded to technical problems and helped to understand the basic settings of the new tool.
At the same time, we created a working group in the technical writers department, whose task was to plan the data storage structure. The whole structure of our server was divided into categories corresponding to the types of projects of the company. Categories, in turn, were divided into spaces by company products. We also identified a separate category for the internal knowledge base.
When those responsible for testing the systems studied the work in Confluence rather deeply, the stage of mutual training of colleagues began. It took about a month to transfer knowledge to the entire department.
Technical problems
The implementation of Confluence as a whole went quite smoothly, but there were problems.
Layout and prepress preparation of documents
“I used to do it in MS Word in a couple of seconds. How to do the same in Confluence? ”- we asked ourselves such a question every day during the entire testing period.
So, it was not at all obvious how to align the contents of the table vertically or assign an icon size less than 16 px.
Indeed, the basic set of page formatting functions in the Confluence WYSIWYG editor is significantly inferior to MS Word, however, the functionality can be significantly expanded if you enter the source code editing mode and work directly with HTML code.
We read articles, watched instructional videos on HTML-layout and shared the solutions we found. We created a separate page in Confluence, where we placed useful information on working with this tool.
Confluence and Plugin Update
After the first update of the main Scroll PDF Exporter plugin, 80% of the macros flew off and the page structure went to Confluence. Later it turned out what happened because of the new functionality of the plugin. Throughout the department, we restored the document structure for several days. After that, we made a plan for updating for the future, which we still adhere to:
- Perform the update on Friday, when the main layer of work for the week has been completed in order to be able to eliminate possible problems on the weekend.
- Distribute to all users of the system to inform them of the time of the planned update.
- Before upgrading, back up the server.
- Update the version of Confluence.
- Test the server, make sure that all information is in place, links to external and internal resources work.
- If you need to update the plugins, back up the server again.
- Update your plugins one plugin at a time.
- Test the plugin immediately after the upgrade.
Bulk Notifications
When the turbulent activity of technical writers and developers finally began to boil in Confluence, the administrator received calls from users of the service. They asked to save them from a mass attack by mail notifications about the actions of other users.
By default, the user only had to go to some page once, after which he was automatically added by the system to the list of observers and received notifications every time this page was changed.
In addition to this, Confluence kindly did weekly newsletters to users listing the most popular Confluence pages. Fortunately, this problem has already been widely covered on the Internet. The solution is to disable the corresponding notifications in the system settings:
Now users receive notifications only if their name is mentioned in the comments on the article.
Server stability
To test Confluence, we deployed a Windows server. In the initial stages, the server often “crashed”. Part of the problem turned out to be insufficient RAM on the server (recommended size is 11-12 GB). The remaining problems were gone when we turned on the system settings recommended in such cases.
Now the server is working quite stably - disruptions occur about 1 time in 2 months. In the event of a failure, a reboot is sufficient to repair it.
Document Management in Confluence
Today in Confluence technical writers, programmers, electronic engineers, QA work together.
We planned to completely abandon MS Word, develop documents exclusively in Confluence and convert them to DOCX and PDF. In reality, it turned out that you can do without the lengthy process of transferring all existing documentation to a new format and then setting up templates in Scroll PDF / Word Exporter. According to our estimates, it would take us about six months to do this. It turned out to be much easier to transfer all developed documents in MS Word format to Confluence and support them there.
We decided not to expect wonderful formatting from Confluence according to all the requirements of ESKD and simply divided all user documents conditionally into documents for the “state customer” and documents for “not the state customer”.
The first we create in the DOCX format, store and update in Confluence. We develop the latter directly in Confluence, export to PDF if necessary.
Thanks to the built-in macros, we use single source technology in user documentation - now we don’t have to manually change one parameter in several versions of documents.
Convenient WYSIWYG-editor makes it easier to make changes to the finished document - screenshots, icons and graphic elements remain in place.
The collaborative editing feature allows you to collaborate on a document. You can share the document with a technical expert directly in Confluence and discuss his comments in real time, and not endlessly spread the document by mail.
To work outside the office, you do not need to configure remote access. To be able to work from home, you only need the Internet.
Confluence offers the user the familiar web page interface with the ability to configure cross-links and open several tabs in the browser for work at once.
Now we store all documents, graphic elements, photos of devices, and we also maintain a knowledge base on company products in one place. There is no need to think about where the source of the pictures or the latest version of the documents can be.
What else do you want to do
We are currently setting up a process for reconfiguring Confluence pages using the Comala Workflow plugin. However, this plugin does not work with MS Word attachments. We coordinate such documents with the help of version comments. Now we are considering options for setting up automatic approval of DOCX attachments. I want the approval and approval process to be used simultaneously with both Confluence pages and DOCX format attachments.
When we set up automatic approval of attachments, we will try to make a quick conversion from MS Word to PDF. And then - sending documents to our printed products server, from where the printing company takes the documents to print.
Sudden Find Instructions
We never managed to abandon MS Word, but in the process of finding a replacement, we suddenly found something more. Confluence brought together developers from different departments, formed the company's knowledge base and became the repository of all company documents, regardless of their format.
Our company has a principle: in any incomprehensible situation, make decisions systematically. We believe that a decision that relies on a model is better than one based on expert opinion or intuition.
In the case of Confluence, Eric Rhys's model from The Lean Startup came in handy. In product development, it helps pivot, change the direction of product development. And in the task of finding a replacement for MS Word, try on a new tool more broadly and find related benefits.
We wish fellow technical writers useful models!
All Articles