Here is early access to the latest episode on the Cherryleaf Podcast – Interview with Anne Gentle, author of Docs Like Code and Product Manager at Cisco. It will be published on the podcast channel on Monday.
- What is docs as code?
- Why do it?
- When might this approach might be applicable?
- The limitations
- Docs like code in development sprints
- Is it only for developer docs?
- Do you you need to understand programming?
- Why did you self publish?
- The benefits of taking this approach
- The future developments
- Automating document builds
Links to topics mentioned:
http://codewerdz.org/ Repository analytics for code and docs
Solr (Search Engine)
Why we use a ‘docs as code’ approach for technical documentation Jen Lambourne, GDS, GOV.UK
My article for tekom’s Intelligent Information blog on Artificial Intelligence and chatbots in technical communication has now been published. It is also available as a PDF on the Cherryleaf website.
We’ve been experimenting with another spreadsheet for calculating the Return on Investment (ROI) on User Assistance.
We wanted to look at: how many support calls an organisation needs to have resolved by users reading the Help content instead of calling Support, before it starts to see a return on the cost of creating the Help.
Using typical costs for an average sized software application, the figures suggest you could break even if you avoided 3 support calls per week.
Contact us if you’d like a copy of the spreadsheet, so you can make your own calculations.
You also find a related Support call cost reduction spreadsheet on the main Cherryleaf website.
Here is an interview we carried out with Mark Baker, author of Every Page is Page One. The interview is interspersed with audio snippets from Day 1 of the UAEurope 2017 conference.
- Caroline Loverage (Thermo Fisher Scientific). Teaching by Example: Worked Examples in the Documentation of Complex Systems
- Kelly O’Brien (Kayako). Practical Information Architecture: Building Templates For Better Content.
- Helena Pichler (Nominet). AsciiDoc to Responsive Webhelp: Agile documentation for small teams/
With thanks to Matthew Ellison and Mark Baker.
Bri Hillmer has written two articles on Just-In-Time documentation (https://www.knowledgeowl.com/home/just-in-time-documentation-a-practical-guide and https://www.knowledgeowl.com/home/just-in-time-documentation). This is an alternative to what she called Just-In-Case documentation. The idea is you write topics that answer real world queries users ask the Support team. This rather than writing a comprehensive user guide, just in case someone wants to know about topic X or topic Y.
This approach focuses on user needs, answering the questions user have. It also provides users with worked examples, each one aimed at solving a particular scenario. In a complex environment, users may need to combine a set of functions or features in order to solve their problems. Sometimes a topic-based approach doesn’t provide that type of information. Just-In-Time documentation could help users understand individual features and how to combine them. And it may be that 80% of the queries relate to 20% of the product’s functionality.
However, this approach does require the technical authoring team to be able to turn around these articles quickly enough. It’s likely that similar topics will come up a regular basis, so there also needs to be a way to reuse some passages of text, in order for the Technical Authors to work in an efficient manner. Also, there might be a legal requirement to provide a comprehensive guide.
Is this an approach you have used? If so, please share your experiences, using the comments box below.
Today, we’ve released our latest training course – Writing skills for developers. The course teaches developers the key skills of technical writing for software user documentation.
Although it would be better for a professional technical communicator to write the end user documentation, for some organisations, this isn’t always possible.
It is for developers who:
- Need a solid understanding of the fundamentals of technical writing
- Want to communicate more clearly and effectively
- What to know how little, or how much, they should write
- Want people to answer their own Support questions
The course comprises 14 modules in total, which delegates can complete at your own pace. The course modules are delivered over the Web in small, manageable video presentations. The course handouts and exercises are downloadable as Word or PDF files.
We can also deliver this course as a classroom course for development teams.
For more information, see: Writing skills for developers training course.
In researching what developers wanted to learn about writing documentation for users, the most common issue related to how much, or how little, they should write. One developer said:
“I would want to know what is the minimum I should write. If you can persuade me what is the necessity of each thing I’m capturing, and the voice I should use to make it most acceptable, I think I’d tune in.”
We’ll look at this question in the Writing Skills for Developers course, which we will be releasing soon. In general, you need to:
- Meet the legal requirements (which differ depending on the product, and the country).
- Provide enough information so that users don’t give up using your product, if they get stuck. For example, how to install the software, and how to get started.
- Consider the support calls, and whether you could avoid any of those by having good user documentation.
That might appear a bit too vague, so let me go back to one of the sentences above:
“If you can persuade me what is the necessity of each thing I’m capturing”
Before you start writing, you should define the purpose and audience for each deliverable you create. There should be a use case:
- Without documentation, is it clear what the user should be doing? is it clear what the user should be doing first?
- Is it clear how they should be doing the task?
- When they have to choose between options, do they have enough information to make the right decision?
- When they have completed a task, do they know what to do next?
- Are there any concepts or terms the user might not understand?
You can assess what topics to cover by doing some basic usability analysis. However, if you think about the tasks, the process (workflow), and any unfamiliar concepts, you will be on the right track.