How to forget about MS Word. Implemantation of Confluence
To implement Confluence, we choose two specialists from the technical writer’s department who studied and tested the capabilities of the tool.
For continuous technical support, the system administrator’s 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 writer’s 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 the company projects. Categories 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, began the stage of mutual training of colleagues. It took about a month to transfer knowledge to the entire department.
The implementation of Confluence in general went quite smoothly, but there were some problems.
Layout and preprint 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 make an icon size less than 16 px.
Indeed, the basic set of page formatting functions in the Confluence WYSIWYG editor is significantly worth than MS Word, however, the functionality can be expanded if you enter the source code editing mode and work directly with HTML code.
We read articles, watched instructional videos about 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 update and plugins
After the first update of the main Scroll PDF Exporter plugin, 80% of the macros failed and the page structure in Confluence was destroyed. Later it turned out that it happened because of the new functionality of the plugin. With all 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 work for the week has been completed in order to be able to eliminate possible problems on the weekend.
- Send a message 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 the right place, links to external and internal resources work.
- If you need to update the plugins, back up the server again.
- Update your plugins one by one.
- Test the plugin immediately after the upgrade.
When started the activity of technical writers and developers 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 about the most popular Confluence pages. Fortunately, this problem has already been popular on the Internet. The solution is to disable the corresponding notifications in the system settings:
Users will now receive notifications only if their name is mentioned in the comments to 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.
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 government 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. Second we develop directly in Confluence and export to PDF if necessary.
Because of 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 send 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 can be the source of the pictures or the latest version of the documents.
What else do we want to do
We are currently setting up a process for reconfiguring Confluence pages using the Comala Workflow plugin. However, this plugin doesn’t work with MS Word attachments. We coordinate such documents with the help of comments to versions. Now we are considering options for setting up automatic approval of DOCX attachments. We want the discussing and approval process to be used at the same time 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 just 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 to make pivot, change the direction of product development. And in the task of finding a replacement for MS Word, make us to study new tool more broadly and find related benefits.