Melissa Weber Mendonça: Writing and maintaining friendly (and interesting) docs

Link to talk information on Plone conference website.

I do open source for a living now. No Plone, but scipy and other scientific libraries. I was at the Python/Plone Brasil conference in 2013. At that percent 10 percent of women at the conference. First Python conference with a code of conduct. I am very happy with that. This year at Python Brasil we had 30 percent women, so very different.

I was using scipy, numpy, and I like teaching, so the first thing I had to do at my job was documentation.

Who likes to write docs? Who writes the docs in your company/project? How often do you read the docs? How valuable is documentation for you?

I want to talk about information, tools, open source, and empathy and anti patterns.

Part 1: information

Some people like to say we are not living in the information age anymore, but in the content age.

Documentation can be narrative: tutorials, how-to guides, books. Also doc strings, code comments, code review comments. Video, talks, slides. Communications, social media. Internap processes, handbooks.

How do we use documentation? We can have various goals. Document technical decisions, explain code logic, a concept, a workflow, a process, structure. Help onboard new people. "You can set the tone for the project. Reach other people, communicate news, events, announcements. What binds it together is that we try to reach other people. This is a very human interaction.

Can you find what you are looking for? Curating information is important, the writer has a responsibility to signpost what is important. Search can be very useful. Keep in mind that people like to skim documentation pages, so help them quickly jump somewhere.

There can be a sea of information. Help people navigate this. We have more information than we can process as humans. Danger is that people find old information on the internet and then file bugs because it does not work. Having official documentation helps.

For organising your content, have a look at https://diataxis.fr. Four types of docs: tutorials, how-to, explanation, reference. This is not definitive, explore and choose one taxonomy that works for you.

Reader profiles: organise your target audience. Are you writing for beginner, experienced, sighted, student, non-dominant culture/language, a child, artist, scientist?  Think about who your audience will most likely be. Take care of accessibility. Identify who your reader is and organize around this. When your docs talk about a person let it not always be a white male, be inclusive.

Part 2: tools define the docs that we write.

If you use Restructured text, you probably try to avoid adding links, because it is a difficult syntax.

Often nowadays projects have "docs as code". So if you use GitHub for your code, you will use issues and PRs for your documentation as well. Often this comes with docs-driven development: if it is not documented, it is broken or does not exist. Technical writers (if they are relevant in your context) may not be used to GitHub and have their own tools. Be careful with credit, authorship, and the limitations of your tools: people who contribute to docs deserve just as much credit as someone who contributes to the code.

Media: where are your docs? On a blog, web, book, in docstrings? Be mindful of how you present your information: audience, goals, voice.

Write/build the docs. As markup language you should look at MyST Markdown (the Plone documentation uses this too). Documentation engines; Sphinx, MkDocs, AsciiDoc, Quarto. More traditional approaches Confluence, Notion, plain text, docusaurus, GitBook/MdBook.

Share it. Is it help for a command line tool? A PDF (probably less links needed, as people may print it)? Web, a book, video, etc. Does your audience know where to find you?

Update the documentation. Your docs may be perfect, but then the code changes and the docs don't match anymore. This is especially hard for images and videos. If you can generate those automatically, that would be a very good idea. You may just need to do frequent reviews. And you may need to version your docs, that old and new versions can be found.

Invite. Interactive documentation draws people in. JupyterLite, PyScript, MyST JS. Translations help for people who are not so good in English. Create docs on how to contribute to the docs.

Part 3: open source documentation

What makes this different from other kinds of docs? So great, there is no boss, so no one can tell us what to do. Oh, but there is no one to tell us what to do, so I don't do know what to do.

You want to lead by example, write docs when you are a project lead. Not RTFM, but WTFM: write the fine manual. Make sure contributors are recognised, valued. You don't need to be an expert to start writing docs, preferably not even!

Onboarding: welcome new contributors. Docs are usually the first point of contact between users and your work. Be clear about prerequisites, unwritten rules push people away. In your project it may be perfectly fine to tell potential new documentation contributors that they need a decent knowledge of C code.

The practice: When there are meetings, committees, other in-person decisions, record this somewhere, make it available for the people who were not there.

The elephant in the room: should we use AI for docs, just let ChatGPT write them?

• No: LLMs are frequently wrong, poisoned or non-sensical, telling you to call functions that have never existed.
• Yes: LLMs can be useful to summarise information for a quick starting point. They can help you index information and identify patterns in your corpus.

Dont't rely entirely on AI tools. If you use them, be transparent about it. Agree on a policy, for example: don't accept PRs that were generated by AI.

Avoid ephemeral media like Discord. Don't say "this is easy", that just creates unnecessary anxiety. Don't use foo, bar, a, b: you can use long variable names, it is allowed.

Celebrate human intelligence. Writing documentation is an exercise in empathy. You are not your audience. Docs are living things, they will never be finished, it is okay to deliver something now, and update later.

"You can't teach people everything they need to know. The best you can do is position them where they can find what they need to know when they need to know it." Seymour Papert

https://github.com/melissawm