Content as an API – Mozilla Developer Network

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.

New training courses in technical communication are on their way

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:

  1. What is technical communication?
  2. The business case for technical communication
  3. History of technical writing standards
  4. Usability and user centred design
  5. Project planning and its effect on writing documentation
  6. Researching and scoping documentation
  7. Estimating
  8. Information design and content organisation
  9. Writing the topics – overview
  10. Presenting different types of information
  11. Index, search and metadata
  12. Single sourcing and reusing content
  13. Post writing​
  14. Researching technical communication – where to go
  15. Establishing standards
  16. Governance and maintenance
  17. What skills does a technical communicator need?
  18. Content strategy and technical communication
  19. Trends in technical communication
  20. Visual design
  21. Publishing and delivering information
  22. Managing the documentation project
  23. Metrics/Evaluating documents

We may develop online courses for some of these topics in the future as well.

News roundup

Here’s a summary of recent activities:

  • We have a client looking to engage a technical editor for a three month contract.
  • We have a client looking for an undergraduate (or recent graduate) to spend 6 to 8 weeks as a paid technical writer intern this summer.
  • 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.

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

What is technical communication, actually?

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

A 2015 book list for Technical Communicators

Two years ago, we asked which books should Technical Authors read, and we received some great responses. It’s always worth revisiting this topic, so please let us know what we should add to this list:

  • Author Experience: Bridging the gap between people and technology in content management; Rick Yagodich
  • Best Practices for Technical Writers and Editors (IBM Press 3 book collection): DITA, Quality, and Style; Francis DeRespinis, Peter Hayward, Jana Jenkins, Amy Laird, Leslie McDonald and Eric Radzinski
  • Central Works in Technical Communication; Johndan Johnson-Eilola and Stuart Selber
  • Content Everywhere: Strategy and Structure for Future-Ready Content; Sara Wachter-Boettcher
  • Content Strategy for Mobile; Karen McGrane
  • Content Strategy for the Web; Kristina Halvorson and Melissa Rach
  • Conversation and Community; Anne Gentle
  • DITA for Practitioners Volume 1: Architecture and Technology; Eliot Kimber
  • Dynamics in Document Design: Creating Text for Readers; Karen Schriver
  • Enterprise Content Strategy: A Project Guide; Ann Rockley and Kevin Nichols
  • Information Space; Max Boisot
  • Letting Go of the Words; Ginny Redish
  • Managing Your Documentation Projects; JoAnn Hackos
  • Microsoft Manual of Style; Microsoft
  • Single Sourcing: Building Modular Documentation; Kurt Ament
  • Technical Communication; Mike Markel
  • Technical Editing; Judith Taritz
  • The Insider’s Guide to Technical Writing; Krista Van Laan
  • The Language of Content Strategy; Scott Abel and Rahel Bailie
  • The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skill; John Carroll

Webinar recording of the changing nature of technical content

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:

What capabilities do Technical Authors want in an authoring tool?

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.

Are there any other features you would expect?