Tom Johnson has written two interesting posts on his blog on the “Documentation as Code” concept:
Documentation as Code can be interpreted in a few ways. Tom describes it as being able to store the documentation with the code:
From a technical angle, Etter argues that one should embrace lightweight markup languages, use static site generators, and store content in version control repositories with engineering code.
An other interpretation associated with this is that documentation should be seen as a design problem; it should be seen as part of the product (and seen in a similar way to the software code), rather than an add-on. If the documentation is stored with the code, it can mean that the requirements for documentation can be more closely linked to the code. When a requirement for a new feature is raised, so can a requirement for the related documentation. It can also mean that content that’s embedded in the UI, presented as on-boarding screens or presented as online Help, can be considered as different potential solutions to each user need.
Documentation as Code is a topic we touch on in our advanced technical writing training course. It’s an approach that we may see growing in popularity.
Yesterday, I saw a presentation by Hazel Southwell on the EU’s General Data Protection Regulation (GDPR), which will be implemented on the 25th May 2018. The impact in its data privacy and protection rules seem likely to affect pretty much every website, with the threat of hefty fines for those that do not comply.
Organisations providing personalised Help content, by storing information in cookies or monitoring the behaviour of users living in the EU by tracking their digital activities, will need to comply with the GDPR regulations. In particular:
- Businesses will have to adopt governance and accountability standards and meet their data privacy obligations.
- Clear and affirmative consent to the processing of private data must be provided, and the relevant information must be laid out in simple terms.
- Organisations need to consider the risks of transferring data (such as the storing of cookies or IP addresses) to countries outside of the EU.
One solution is to require users to log in to see information. However, this may be an unpopular and impractical solution for many users.
Here is a diagram that shows the different types of User Assistance that can help users as they progress through the customer journey:
Supporting the user through the customer journey has become more important, partly because the subscription, “try before you buy”, sales model means users can stop being a paying customer at a moment’s notice. Today, all of the information you provide, both pre- and post- sales, needs to provide the same consistent, high quality, experience to the user.
Have we missed anything out? Let us know if you think the image should be changed in any way.
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.
Continue reading “A technical communication user’s hierarchy of needs”
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 “Stack Overflow is moving into documentation (get the popcorn)”
We’re moving our public classroom course on Trends in Technical Communication Course – Advanced Technical Writing Techniques from the 18th September to Tuesday 22nd September. There are places available if you’d like to book.
We’ve also run this course a number of times during the summer as an “onsite” course for clients, using WebEx and Lync (soon to be called Skype for Business). Using online meeting technologies like these means we can deliver training to authoring teams throughout the world.
We have been asked if individual delegates overseas could use these platforms to participate in our public, classroom, course. I’m afraid we don’t offer this. The “online meeting” courses involve using special lighting and audio equipment that isn’t available in the training rooms we use for the public courses. Also, it would be very difficult for the trainer to manage two different delivery methods simultaneously.
There’s an interesting discussion thread in the ISTC’s discussion forum regarding good and bad examples of technical writing. Incoming ISTC President Alison Peck has been asked by a researcher for a radio programme if she could provide some examples of technical writing: “well done, badly done and particularly innovative or strange”. As it’s a radio programme, these examples are likely to be read out.
This is not as straightforward to answer as you might think.
Firstly, most technical communicators work under non-disclosure agreements, so the best and worst examples often aren’t for public consumption.
Secondly, a lot of poor examples are from content that has been badly translated into English. They may have been well written originally, but they might have become mangled through the process of localising the content.
Thirdly, as Alison pointed out in her original message in the online forum, reading out very basic instructions out of context is not going to be particularly riveting or easy for the listener to grasp.
Fourthly, although technical communication is about clear communication – clear sentences – the role of technical communication is mostly about addressing the question, can the user do the task?
Minimalism, which most technical communicators use, focuses on:
- Adopting an action-oriented approach (to minimise the amount of reading)
- Starting immediately on meaningful tasks
- Supporting users in recognising errors and recovering from them
That requires more than clear and simple sentences; it requires information design as well. This means any examples ideally should show how well or badly they enable the user to complete the task. That requires an understanding of the task itself, and this makes it difficult to do this in a few seconds on the radio.
Peter J. Bogaards posted a link on Twitter yesterday to an article and a press release on how IBM is adopting a design-led approach to software design.
“IBM Design Thinking is a broad, ambitious new approach to re-imagining how we design our products and solutions … Quite simply, our goal — on a scale unmatched in the industry — is to modernize enterprise software for today’s user who demands great design everywhere, at home and at work.” (Phil Gilbert, general manager, IBM Design)
I understand the IBM Design Thinking approach will affect everything it does: product development, processes, innovation, and, interestingly, the technical documentation/user assistance associated with products. Both design and traditional technical communication share the same goals – to deliver something that is very usable, robust and aesthetically pleasing – so it makes sense to have the two teams aligned closely.
Continue reading “Design-led technical documentation”