Mozilla is an organisation that always seems to be doing innovative things with their documentation. One of the experimental functions it has introduced to its Kuma wiki platform for the Mozilla Developer Network (MDN) documentation is an experimental PUT API that makes it possible to create and update articles remotely.
Mozilla suggests a number of ways it can be used:
You can create a page for your project and update content in certain sections from automated build, testing, and deployment scripts. This can help you keep your community up to date with your project’s progress.
If your project offers documentation alongside source code, you can push HTML renderings into a subsection of MDN. This lets you maintain docs in a way that’s appropriate for your team’s workflow, while still contributing to MDN and allowing localizers to translate the content.
Fro example, Mozilla’s programmers are able to write scripts that automatically generate articles based on contents of header files they’re creating. The API uses HTTP, which means software engineers (and other writers) effectively have the freedom to use the application environment and libraries of their own choice.
Kuma itself is an open source platform written by Mozilla in Python, using the Django framework. Contributors can fork the Kuma repository on Github, make changes to the content, and push the revised content back to the wiki.
It will be interesting to see if this succeeds, and if this type of platform extends further out than its use for developer documentation.
It might seem like we’ve been quiet recently, but that’s partly because we’ve been working on an academic project that we hope to be announcing towards the end of the year.
As a spin-off from this project, we’re developing new training courses in technical communication. These courses are at a more advanced level than our basic/intermediate courses, and they include more references to academic research.
If you are considering any on-site training for your technical communications team, we can now offer these topics:
What is technical communication?
The business case for technical communication
History of technical writing standards
Usability and user centred design
Project planning and its effect on writing documentation
Researching and scoping documentation
Information design and content organisation
Writing the topics – overview
Presenting different types of information
Index, search and metadata
Single sourcing and reusing content
Researching technical communication – where to go
Governance and maintenance
What skills does a technical communicator need?
Content strategy and technical communication
Trends in technical communication
Publishing and delivering information
Managing the documentation project
We may develop online courses for some of these topics in the future as well.
We’ve a client looking for information on applying Net Promoter Score to user assistance documentation. If you’ve seen anything, please let us know.
Cherryleaf’s Ellis Pratt will be the guest speaker at June’s “Member Masterclass @ The IoD”. The topic is clever content creation in business. We’ll look at some of the most effective techniques for creating the types of content created in today’s business world. The event will be held at 6pm on 2nd of June 2015, at the Institute of Directors, 116 Pall Mall, London.
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:
As a technical communicator, sometimes it can be hard to explain to others what it is you do. In the olden days, it was simpler: you could say you wrote manuals. Then, in more recent times, you could say you wrote online Help and manuals.
Today, there can be uncertainty of what is and isn’t technical communication. It can be unclear if certain deliverables should be created by a technical communicator or by someone else. For example, if content moves from a Help page to an onboarding screen, is it still technical communication? If the text moves into the interface, should the technical communicator create it? Are walkthrough videos a function of training or technical communication? Continue reading →
STC France-TCeurope has published a recording of Ellis’ webinar presentation on the changing nature of technical content. The presentation lasted 50 minutes, followed by 10 minutes of questions and answers:
We were contacted last week by a SaaS developer who wanted to know if their solution might be of interest to companies needing to write and host their product’s user manual or online Help content. So what capabilities do Technical Authors look for in an authoring tool?
There were a few features that sprung to mind:
Multi-channel publishing (for example: publishing to the Web, Microsoft Word and PDF). PDFs are still important as a publishing option, as people still like to read good quality printed content.
Separation of look and feel from content.
Content re-use (write once, re-use many times). This is different from simple cut-and-paste.
Variables (so it’s easy to change product names).
Conditional text (content that can vary depending on the type of user or type of product).
Link management (being able to find content in the project quickly, as well as being able to manage the dependencies among links and topics).
The ability to handle larger documents (200+ page documents with screenshots on most pages)
Expanding/collapsing table(s) of contents (and even different tables of contents for different types of users).
A user-friendly authoring environment.
Version management of the content.
Ideally, there would also be:
A way for occasional users to add and edit content without breaking formatting styles, using a User Interface that didn’t overwhelm them.
Access to and shared management of the content. This is so that writers could collaborate with each other, working on different topics for publications at the same time.