Advent of Technical Writing: Navigation Structure (Day 1 of 24)
jamesg.blog
jamesg.blog
Further reading on technical writers and startups (knowing your audience, role, and more): https://jamesg.blog/2023/11/27/technical-writing/
I welcome ideas for what I should write about in the series! I have a couple of exciting ideas to explore; more would be sincerely appreciated.
Now I need to remember to read each new entry... (Which is entirely on me, just to be clear!)
I wish I could get my teammates to write any docs, let alone good documentation. It doesn't help that we barely have time for tech debt due to leadership priorities.
I suggested some technical writing courses, but they got weird ideas from them, like writing documentation in a conversational style, which makes it somehow even worse...
The most common form of bad documentation I come across is simply documentation with pieces missing: it uses terms without defining them, it tells you what problem an option is intended to solve but doesn't say what effect it actually has, and so on.
One possible cause is the "empathy" theory: the author missed that bit out because they assumed the reader already knew it. But I think it's more common that the author just did a half-way job, because we don't have a documentation culture that takes being complete and correct as the minimum baseline.
If that's the case, I think the advice authors need is to _not_ spend so much time thinking about what their reader is trying to do, and spend more time thinking "is what I've written complete?".
After reading this, I wrote a blog post. It will be part of the series, but probably released in a few days. I have so many ideas to cover! Now it's past midnight though, so I should probably get some sleep!
Thank you for the ideas!
I wrote documentation for a product earlier this year. A colleague with limited Python knowledge tried out the product using my documentation live, on a call. I learned so much from the process. We found bugs, we noticed that our documentation didn't have one clear usage path, which was confusing, and more.
Watching someone work through your documentation was a bit uncomfortable, but it really helped me. I plan to do it again with another documentation project on my hands.
Also, your colleague may need more direct feedback. I have picked up a lot of tips from the person who edits my work. Sometimes, I have an "aha" moment when I'm like "hm, this approach really is better!" and I take it with me in all that I write after that.
> writing documentation in a conversational style
The medium really matters. If the course was more about tutorials, a conversational style can be appropriate, if kept in check. If you are documenting open source software, it is different. Your colleague probably picked up good tips, but the course may not have shown how to use them properly.
I wholeheartedly agree with this. If you do this, especially with a user who is known for asking good questions, you will benefit greatly from it.
In general it's very helpful to study lots of docs sites to get fresh ideas about different ways to order docs. But I also recommend being careful about apples-to-oranges comparisons. The intuitive ordering for a narrow Python math library is probably different than the intuitive ordering for a sprawling web framework, for example.
1. The minimum amount of information someone needs to use a project. In this case, that is the "what is", and showing how to run fine-tuned models. 2. Generally useful information that someone can use to evaluate / understand the project. In this case, supported devices.
A reader could skip these if they know for what they are looking, but if someone is new to the project a Getting Started section equips them with what they need.
For Python packages generally, I like to include an abridged version of functionality in a quickstart / Getting Started section. Then, usage examples can have either their own page, or examples with example outputs that are in the code and are propagated up through automated docs. [1] [2]
For small packages, I usually fit all of it in a README; having a strong quickstart, in all cases, is essential. [3]
[1]: https://indieweb-utils.readthedocs.io/en/latest/indieauth.ht...
[2]: https://supervision.roboflow.com/annotators/#supervision.ann... (I didn't write this page, but I like the style and it is auto generated from docstrings)