Perfecting collaborative authoring for online Help

Yesterday, I wrote:

“There are some activities that seem like they always could be improved. One is creating an authoring environment where professional technical communicators and other staff can work together.”

Writing online Help is different from writing some other types of content, in that it involves topic-based authoring. Content is stored in modular, re-usable and flexible chunks of information. By moving away from a page-centric, document model, you’re able to organise and present published information in many different ways. However, it’s a different approach to what many non-professional Technical Authors are used to. Unfamiliarity with this content model, as well as the tools, can make collaboration difficult.

Continue reading

Using Markdown to create a boilerplate document for reports and proposals

Following on from our post Cutting and pasting content into Word documents – Is there a better way?, we’ve been looking at how organisations could use Markdown to create reports and proposals more quickly and consistently.

The objective was to:

  • Create something simple for non-technical people to use.
  • Have a collection of re-usable chunks of content that could be embedded into the document (no more cutting and pasting). If a chunk needed to be changed, then the documents where it is embedded would reflect that change automatically.
  • Be able to generate the completed report as a .docx (Microsoft Word) file.
  • Separate the content from the “look and feel”.
  • Enable different people to work on different sections of the document simultaneously.
  • Store the content in an open format, so there was potential to use some of the content in other places (such as on a website).

Continue reading

Stack Overflow is moving into documentation (get the popcorn)

Stack Overflow, a collaboratively edited question and answer site for programmers, has announced its plans to add documentation to the site:

“Lately we’ve been asking ourselves “what else could we do to improve developers’ lives on the internet?”. Jeff’s original announcement of Stack Overflow said this:

There’s far too much great programming information trapped in forums, buried in online help, or hidden away in books that nobody buys any more. We’d like to unlock all that. Let’s create something that makes it easy to participate, and put it online in a form that is trivially easy to find.

Stack Overflow has made all of that a lot better, but there’s one area that is still hanging around: Documentation. Just like Q&A in 2008, Documentation in 2015 is something every developer needs regularly, and something that by most appearances stopped improving in 1996. We think, together, we can make it a lot better….

…We’re hoping we can improve documentation, not just move it under the stackoverflow.com domain.”

It will be fascinating to see how this project progresses – what issues they encounter, how they tackle these, and if the solutions work.

Continue reading

Content as an API – Google’s engineering documentation

Google’s Riona MacNamara presented at the Write The Docs North America conference on “Documentation, Disrupted: How Two Technical Writers Changed Google Engineering Culture“. In the video of the presentation below, Riona explains how she worked with a small team of writers and engineers to build a documentation platform in six months that is becoming a part of the standard Google engineering workflow.

Atlassian no longer lets users comment on its documentation – good or bad news?

Last week, Atlassian sent out this message on Twitter:

This was a surprise, as Atlassian has been a strong advocate for having user comments appended to user documentation. Sarah Maddox, when she was working at Atlassian, posted the reasons why the company encouraged comments on her personal blog:

Continue reading

The big questions in technical communication

David Farbey wrote a semi-existentialist post on the challenges for technical communicators yesterday. I’d like to look at the issue in a different way, by looking at the big questions in technical communication today. The answers to these questions (which may be decided by people outside of the profession) are likely to affect the future direction for technical communicators.

Continue reading

The federated Help authoring system

The federated database is a term that has been growing in popularity in recent months. According to Wikipedia:

Through data abstraction, federated database systems can provide a uniform user interface, enabling users and clients to store and retrieve data in multiple noncontiguous databases

Could a similar approach be used in the field of technical authoring – could we have federated Help authoring systems?

There’s a number of situations where a federated Help authoring system might be needed:

  1. A company is selling a system that includes products from other organisations. For example, a telephony solution might include handsets supplied from a third-party manufacturer. This systems integrator is likely to want the handset manuals to use their product name, “look and feel”, contact details and company logo.
  2. Another subsidiary or department is creating documentation in their own Help authoring system, and you need to include some of their content in your user documentation. For example, these could be Knowledge Base articles created by the Support department, or embedded Help written into the application screens by the programmers. They cannot or do not want to use the same authoring system as you, and you don’t have the authority or desire to enforce your system on them.

There are a number of ways a federated Help authoring system can be set up:

  • One is to agree a common data structure. You could require your suppliers to make their user guides accessible in DITA format (instead of, for example, InDesign). You would need to define which text you wanted to be conditional – such as the company name, product name and contact details. In a federated model, their content would stay in their system, but could be integrated with your content when you generate the user documents. This means if they updated the manual, these changes would appear in your system.
  • Another approach is to simply have the content as an embedded object in your authoring system. You would need to get your colleagues to create content where the formatting information was not embedded with the content itself, and again you’d need to agree which text you wanted to be conditional.

The attraction of this approach is it minimises the effort required by the other writing teams, and it provides a solution where you don’t have the ability to establish a single authoring solution.

If you’re doing this today, feel free to share your experience.

Book review: Confluence, Tech Comm, Chocolate

I was sent a review copy of Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication, by  Sarah Maddox. It’s about using wiki technology for developing and publishing technical documentation, using the Confluence platform, the emerging trends in the creation of User Assistance and, in places, chocolate.

Confluence, Tech Comm, Chocolate

The book is aimed at three audiences:

  1. The person who isn’t sure what collaboration tools and wikis are, and is not yet fully convinced these are platforms they should use for producing and publishing technical documentation
  2. Someone who has used Confluence or another similar application, but sees themselves as a beginner
  3. Advanced users of Confluence.

The author manages to pull it off  – all three groups will find the book interesting and useful.

For the skeptics, Sarah raises and answers a great question:

Isn’t a wiki just a puddle of chaos?

The problem with the word “wiki” is everyone thinks of Wikipedia, with its complicated authoring environment and occasional errors. Sarah explains not all wikis are like Wikipedia, and how Atlassian, the makers of Confluence, struggles to describe the software (it currently says it “provides collaboration and wiki tools”). In fact, Confluence is a tool that can publish EPUB ebooks, PDFs, Word documents, HTML, DocBook files and, probably quite soon, DITA files. It has a rich text editor that looks like Word. It’s a wiki that doesn’t look like a wiki.

The book itself was written in Confluence. Comprising 477 pages, there’s a lot of “meat” in this book. We’d consider ourselves as knowing a lot about Confluence, having used it to build solutions for a number of clients, but there were many useful nuggets of new information.

Enthusiasm oozes through almost every page. That’s partly because Confluence is one of those tools that causes clients to get excited. They very quickly realise the potential outside of the original project. It’s also partly because the author is passionate about the subject.

Examples are built around a hero (heroine, actually) called Ganache, and this approach works well.

The book also looks at new trends in User Assistance – where technical documentation is going and how it will be created. A Cherryleaf article is mentioned in passing. It looks at working in an Agile software development environment, and how a collaborative authoring environment can help reduce the authoring bottleneck Agile can produce.

Sarah also highlights the weaknesses of authoring in this environment. There are issues around round tripping (and whether it’s needed or not), in particular.

Technical Writers will also have questions about translation and localisation of content, which is touched on only briefly. Publishing to .CHM files isn’t covered. However, there is a wiki that complements the book, so readers have the opportunity to raise these questions with the author (and discuss them with other readers) there.

If you’re interested in collaborative authoring, wikis, Confluence, chocolate, working in an Agile environment or where technical documentation is going, then it’s worth getting this book.