This guest blog was written by Thomas Walker, the technical writer at K15t Software.
As any tech writer will tell you, creating good technical documentation is a collaborative effort involving not just writers, but also engineers, product managers and customer support among other roles. And that’s a big part of why it’s also so difficult. Inter-departmental collaboration is often challenging, disruptive, and time consuming. But times are changing, and thankfully there are modern software tools that can support you in overcoming this challenge. For us at K15t Software, Atlassian Confluence is the crux of the solution. It serves as the editorial system for all our tech docs. And in this role it’s truly game changing, because so many aspects of its functionality support the collaborative nature of writing technical documentation.
Collaborative doc creation
In order to write great technical documentation, a tech writer needs to collaborate – by talking to engineers about new features, discussing new use cases with product managers, or by asking customer support for input on users’ most frequent challenges. Breaking down information silos by bridging communication gaps not only helps tech writers create technical documentation, but more importantly, it benefits the user as tech docs will be more precise, informative, and helpful when all of these various stakeholders contribute to their creation.
As an editorial system, Confluence makes it easy for a tech writer to get colleagues from different departments involved. Its editing, commenting, and sharing functions allow tech writers to request feedback or input right within the relevant page, paragraph, sentence, or word. But more importantly, it’s so intuitive to use that it allows my colleagues to respond quickly without having to spend time figuring out how to use the tool to deliver the requested information.
With more traditional editorial systems, requesting and receiving input often takes a long time – meetings might have to be scheduled, proposals may have to be approved, etc. But receiving feedback and information quickly is key, as tech writers need to keep up with frequent release cycles (especially in agile working environments). This is where Confluence really helps. While I’m writing the first draft of a product’s documentation, I often use inline comments or @-mentions to request information from our software developers. They then receive a notification which gives them the freedom to reply whenever they have a free moment. In the meantime, I continue working on the rest of my draft. Alternatively, our developers can add any information directly to the draft itself instead of sending me an email or a Word document. This saves both of us the time it would take to schedule and attend a meeting (which is even harder for organisations with remote teams) – resulting in faster turnaround times and up-to-date documentation.
Another side effect of an agile work environment is that, because things can change quickly, it’s hard to remember discussions from a month ago. Yet remembering these details can be quite important when revising tech docs. I often find that while a discussion may not be relevant to a current release, it certainly impacts the next. By using page comments in Confluence to discuss or document verbal discussions, you can keep track of any decisions that were made or are still outstanding. All you need to do is browse through the comments to catch up and see if it influences your current release docs – a real godsend when you are under time pressure. Moreover, if there are still open questions, I can just restart the discussion in the comments without having to bring people up to speed on an individual basis.
Painless doc proofing
After all the information is gathered and the writing is done, it’s time to proofread, rewrite and ultimately approve the documentation for release – another process dependent upon collaboration. Having a second pair of eyes proofread is actually an essential step if you want to write good documentation. It’s a great way of catching language errors, and also of testing the docs before they are published – especially if the proofreader isn’t familiar with the product. They can point out parts that aren’t easily understandable or are too complicated. Confluence supports this process by letting proofreaders add feedback and make revisions exactly where they are needed – within the text itself.
If we used a word processor like Microsoft Word to draft our technical documentation, we would need to send versioned files back and forth in order to proof and revise content. This is an insanely annoying and frustrating process, especially if there is no stringent versioning process in place (v2.doc, v2-final.doc, v2-final-FINAL.doc, and so on). Confluence will always show you the most recent version of a page, including all changes and added comments – so you’ll always have one document to work in. Seeing what changes were made or which comments were resolved is as easy as clicking the page history button. You’ll be able to see who added text, deleted a paragraph, or made changes to the document’s formatting. And in case you notice that an earlier version of the documentation was more accurate, you can easily restore it.
Another feature I’m particularly fond of is collaborative editing. It was introduced in Confluence 6, enabling different people to concurrently work on the same document without inadvertently overwriting one another’s edits.
Because tracking changes and discussing revisions is so straightforward, you can easily ask a third person to proofread your documentation. They’ll be able to see which discussions have already taken place, and add fresh perspectives on the decisions that have been made in the comment threads.
Straightforward doc publication
Publishing technical documentation is one of the only steps that probably benefits from not being collaborative. The process of uploading your tech docs to your help pages or exporting them to PDF should be simple, fast, and not involve too many people. At K15t Software, we’ve implemented a straightforward process that eliminates the need to duplicate content or involve anyone who isn’t directly responsible for technical documentation.
As a tech writer, I can directly publish technical documentation written in Confluence to K15t Software’s help pages by using our Scroll Viewport add-on – making the publication process faster and leaner. This blog post features some examples of companies that publish their online docs in just this manner. Moreover, by using the version management add-on Scroll Versions in combination with Scroll Viewport, I no longer have to go through the process of publishing an entire documentation space. Any approved changes I make are dynamically published to the appropriate version of our documentation – saving us time and improving our users’ information experience.
While the publishing step shouldn’t be too collaborative, revisions in order to improve documentation certainly should be. Of course, everyone wants to create perfect documentation from the get-go, but it normally doesn’t happen that way. Continuously improving documentation is definitely a goal worth pursuing, and you’ll want others to easily be able to collaborate with you on this. Users as well as co-workers often have great insights, comments and suggestions on how to make your docs better. I collect all of these in Confluence, in page comments, through inline comments, or by linking JIRA issues with relevant information to certain Confluence pages. That way, I can browse and extract suggested changes in exactly the location where I’ll be writing the next iteration.
Collaborative processes deserve collaborative tools
Hopefully it’s quite clear that technical documentation is a collaborative process, and those responsible for creating it require – or perhaps more appropriately, deserve – tools that support them in their collaboration efforts. This is where Confluence really shines as a tool, supporting and improving our tech doc collaboration on a daily basis. If you would like to try it out (free for 7–30 days) just head over to Atlassian’s website.
