Creating user documentation and online Help in a Continuous Integration/Continuous Delivery environment can be challenging for technical communicators and developers.
Last week, I spoke at, and attended, Madworld 2016, the conference hosted by MadCap Software for its users. Here is a summary of what I saw and heard on the second day. These were mostly for advanced users; I didn’t see any of the presentations aimed at new users of Flare.
The results from the Stack Overflow 2016 survey have been announced this week. It identified poor documentation as the second most common workplace gripe for developers.
We’ve started work on a new training course about planning, writing and managing an API documentation project. Primarily aimed at REST APIs, this will help you to organise, plan, author and control your API documentation. This course is aimed mostly at people who are not developers, and no programming experience will be required.
The exercises are based around an imaginary API for hospital management system, as most people are familiar with what a hospital is, and what happens inside.
We have have completed the presentation, bar a few teaks, and we are now developing the course exercises and answers. The slide deck currently runs to 256 slides, which means this will almost certainly be a two day course.
We think this course is probably best suited to being delivered in a classroom. We may also offer it as a live, web-delivered course using webinar software for teams based outside of the UK. We might develop a recorded e-learning course at some point in the future, but it’s not something you’re likely to see for a while.
For more details, see Documentating APIs – training course.
We asked Technical Authors to complete a survey into the issues and challenges they face in 2016 and beyond. There were four main themes that stood out:
- Issues around working in an Agile environment.
- A need to develop skills in creating training screencasts. This included how to use tools, structuring and presenting content, and the ideal length of each video.
- Improving the status of Technical Authors and the Technical Publications department in the organisation. This topic has come up in previous surveys.
- Developing skills in using DITA.
We’ve looked at Agile recently, and we’ll revisit the other topics in the upcoming months.
Thanks to everyone who took part in the survey.
Judging by Social Media last week, there were many strong opinions at the tekom tcworld conference towards the DITA authoring standard and the associated tools. It seemed, as the philosopher Swift once said, “Haters gonna hate”, and, by inference, “Hypers gonna hype”.
Eliot Kimber provided an interesting summary in a post to the DITA users group forum (Trip Report: Tekom 2015, DITA vs Walled Garden CCMS Systems):
“For background, Germany has had several SGML- and XML-based component content management system products available since the mid 90’s, of which Schema is probably the best known. These systems use their own XML models and are highly optimized for the needs of the German machinery industry…These products are widely deployed in Germany and other European countries. DITA poses a problem for these products to the degree that they are not able to directly support DITA markup internally, for whatever reason, e.g., having been architected around a specific XML model such that supporting other models is difficult. So there is a clear and understandable tension between the vendors and happy users of these products and the adoption of DITA…
…It’s clear to me that DITA is gaining traction in Europe and, slowly, in Germany but that the DITA CCMS vendors will need to step up their game if they want to compete head-to-head against entrenched systems like Schema and Acolada. Likewise, the DITA community needs to do a better job of educating both tools vendors and potential DITA users if we expect them to be both accepting of DITA and successful in their attempts to implement and use it.”
This may have led those who are asking, do I need DITA?, to come away from the conference more confused than before. So, we thought it might be useful to provide a rough guide to whether it’s worth adopting DITA:
You probably don’t need DITA if:
- The way the content looks to the user is the most important issue.
- You have fewer than four writers.
- You write narrative content.
- You have limited budgets for tools, training and migration.
- You don’t have the time to deal with the issues around changing working methods.
- Your content has a “shelf life” of less than two years.
- You use a lot of graphics with annotations.
- You need to customise outputs [added] for individual documents [added] (such as PDFs).
- The cost of migrating existing content will be expensive.
- You want the presentation layer embedded with the content layer.
- You don’t want to work within strict rules regarding how topics are written (where content is marked up semantically).
- You need to use the tools used by developers or the marketing department.
- You want a simple information architecture.
You might need DITA if:
- You need to write to (and enforce) a standard.
- You need to localise content into many languages.
- You have more than four writers.
- You want to write semantically.
- You need a more efficient authoring, [added] reviewing [added] and publishing process.
- You create many variations of the same document.
- You want intelligent content that can adapt to different users and contexts.
- You are spending too much time on formatting content.
- You need to re-use content in different projects and different contexts, and make those topics accessible to other writing teams who might want to re-use them.
- You need to establish a controlled vocabulary and taxonomy.
- You want content validated for consistency.
- You want automated publishing.
You probably do need DITA if:
- You need to share content with other organisations.
- Your content will need to last more than 30 years.
- You want content to be stored in an open data standard, independent of any tool.
- You don’t want to be tied into a specific authoring tool, content management system or publishing/rendering engine.
- You need transclusion (where an element can replace itself with the content of a like element elsewhere) across a range of media.
- You want to have a way of generalising back to a common standard.
Do you agree?
Please share your thoughts below.
In the radio series, A History of the World in 100 Objects, Neil MacGregor, Director of the British Museum, described the oldest man-made object in the museum – the Olduvai stone chopping tool. This was made approximately 1.8 million years ago in Tanzania, where the first humans originated.
MacGregor explained the tool has more than six chippings that sharpened this rock into a tool, when it only need two. He said:
“Those chips tell us that right from the beginning, we, unlike other animals, have wanted to make things more complicated than they need to be.”
Complexity, it appears, has been part of product design and manufacture right from the beginning. Did the need for user instructions follow shortly afterwards?
At the TCUK 2015 conference, Rachel Johnston mentioned the idea of a content maturity model. We thought we’d take this idea and ask:
Could we develop a model that illustrates a hierarchy of needs for users of technical communication (and in particular, User Assistance)?
A model of what?
We suggest calling this model a technical communication user’s hierarchy of needs. This is because we’re considering the different points where a user interacts with technical communication content, the information they need, and value it gives to them.
It takes a similar approach to the content maturity model Rachel suggested (shown in the photo below), with the least mature organisations providing just the legal minimum, and most mature content systems contributing to branding and evangelism.
A user’s hierarchy of needs also enables us to compare this model to similar models from content marketing and product design. For example, the categories in our model’s hierarchy roughly correspond to Peter Morville’s “User Experience honeycomb”, as well as the key elements in product design.