This month I had the pleasure of attending my first ever documentation conference – Write the Docs! In fact, it’s the first conference I have ever been to. It was virtual this year but they are hoping to be back ‘in person’ by next year. I was very excited to meet more technical writers and see what I could learn from the talks. I’ve chosen to summarise just four of the talks, but there were many more. All the talks are posted on the Write the Docs YouTube channel.
‘How I convinced my boss to build our docs team’ by Karissa Van Baulen
This topic has always been a bit mysterious to me, as I’ve never had to try to convince anyone to build a docs team. I found it insightful. I also appreciated that her method could be reproduced.
She began by asking two fundamental questions:
- When is it time for a team? Answers may vary, but it’s time for a docs team if you are struggling to scale the docs in line with the company scaling up.
- How can you prove it? User statistics and how they apply to you and your company.
Her first task was to write a proposal to someone who has never seen a technical documentation in their life. She reminded us that not everybody knows what you know, and broke the proposal down into a simple format by spelling out what problems are being solved with extra resources. She also recommended finding an advocate within the company who believes in your vision.
As her second task, Karissa audited the current documentation, which sounds like a big scary task, but she broke it down:
- People and process – Who reads the docs? How are they written (tools)?
- Appearance – Content organisation, visuals and discoverability.
- Competitors and industry – Look at their docs.
- Content – Is it up-to-date? How many pages are there?
For her final task she then moved to metrics! In order of importance:
- Feedback – User based, which tells you key facts about your docs. Karissa highlighted this as the most important factor when trying to convince someone to invest in a team.
- Analytics – Helps visualise users’ time on your docs.
- Basics – Health metrics of your docs. Google Analytics.
Using these statistics and metrics, and with a colleague on side, she was able to grow her docs team.
‘Documentation as marketing?’ by Mano Toth
Mano began his talk with a very honest disclaimer: there are no straightforward answers to this question as it all depends on where you work, and what your company needs.
He has been a technical writer for some time and became aware of the “supposed conflict” between technical documentation and marketing. They are generally seen as two different disciplines, but he believes we can work together towards shared goals. He organised his talk by answering three different questions.
Can we collaborate?
According to the book Technical Communication by Markel, the main goals of technical writing are:
- Honesty
- Accuracy
- Clarity
How different is this really from marketing? Marketers look for honest stories that resonate with people. Marketing offers solutions (just like we do).
Why do we need to collaborate?
We can sum up some of the common goals of technical writing and marketing as:
- Helping users/prospects decide – engage them
- Help users/prospects solve their problems- retain them
- Enable users/prospects to explore – up selling and cross selling
How do we collaborate?
- Discoverability – SEO (Marketers have been seen as better at this in the past with more knowledge around the subject, so we can learn a lot from them here.)
- Clear message about capabilities.
- Unified user experience.
- Keep users ‘in flow’.
As Mano concluded his talk to virtual applause, I think a lot of writers had come around to his point of view. A very well organised and delivered talk.
‘Beyond spell checking – what else can we check automatically?’ by Tibs
This talk looked at plumbing linting into your Docs-as-Code workflow. Now this was something I had never heard of before, so I found this talk very interesting.
Lint was a program written in 1978 to find common errors and style problems in C code. Linting is now also applied to text!
The idea here is that linting checks your text, but ultimately the final decision to merge/publish should be with a human. Preferably a sensible human. These are local checks in your text editor that can be run at any time, but the advice from Tibs was to run them on your docs before review.
Tibs also pointed out that we could consider having them run before you commit. It might be a bit much if you can’t commit before fixing any errors or warnings that flag up. All the same it’s probably a good idea to hold off on merging before fixing errors.
Common checks to run:
- Check: Use ‘this’ instead of ‘that’. Useful for common mistakes, which you can flag up as errors or warnings. Use errors for issues that must be fixed, and warnings for issues you might need to fix.
- Check: If ‘this’ is present, then we need ‘that’ as well. For example, if the abbreviation ‘WHO’ is present, then we also need ‘(World Heath Organisation)’.
- Check: Capitalisation
- Check: Check for absences, such as missing ‘alt’ text on images.
Tools to consider (most of them are FREE):
Having never heard of linting before, this was a very exciting talk for me to attend. You can configure your own checks, but most of these tools offer quite a few out of the box. I have bookmarked the pages for each tool to read the documentation around them at a later date.
‘Creating documentation for the African audience’ by Benny Ifeanyi Iheagwara and Mustapha Rufai
The presenters surveyed different companies to find out how they were creating docs for their audience, what workflows they were using and what tools they were using. This presentation was originally intended to give us a bird’s eye view of this.
Included in the presentation there were a lot of very interesting statistics. They were collected in a joint venture between Google and Accenture who created an African Developer Report in 2021. Why are we looking at a developer report? Simply, as the developer community across Africa grows, so does the need for documentation.
Dear reader, a word of caution before diving into the full report. It spans 68 pages so is not a light afternoon read, or a crash novel for the airport. It may require a strong pot of coffee for a serious deep dive to satisfy your curiosity. It does contain a lot of very interesting information, and the graphical representation of data is wonderful. The full report can be found here.
I’m just going to outline a couple of statistics that really stood out to me below.
- Google estimates that there were 716,000 developers across Africa in 2021.
- Using Crunchbase, there are an estimated 24,000 start-ups with headquarters in Africa.
How are these companies approaching their documentation? Again there is no straightforward answer. “It depends” should be a common refrain by now. The documentation strategies used vary by industry, tools, community and teams. Our hopes for a bird’s eye view were dashed, however I should have really figured out that with documentation there won’t ever be a one-size-fits-all approach.
It became clear to the presenters that companies were either building their own content management systems or using third-party services. They did note that there is currently a drive to engage more with the end users, and more research and investment is being undertaken to do so.
As for the challenges to producing good documentation in Africa, the presenters realised that they are practically the same challenges that all technical writers may encounter. From there being no dedicated docs team (so no ownership of the documentation) to trying to document clunky legacy code, and having a hard time persuading people to engage with documentation.
It was interesting to hear that those of us following a Docs-as-Code approach are all using essentially the same tools (Git, Jekyll, Open API spec, VS Code and other text editors). My own take-away from this talk was that writing for the African audience is similar to writing for any audience. If you try to keep your reader in mind when writing, and aim for clear and concise writing, then the end result should be the closest thing to good documentation that it can be.