4 ms·

Advent of Technical Writing: Navigation Structure (Day 1 of 24)

93 points by zerojames 3y ago

zerojames 3y ago
Day two of this series is out, too): https://jamesg.blog/2023/12/02/navigation-links/ https://jamesg.blog/2023/12/02/navigation-links/ Further reading on technical writers and startups (knowing your audience, role, and more): https://jamesg.blog/2023/11/27/technical-writing/ 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.
- pivic 3y ago
  Perhaps a list of bibliography tips? Here's my five cents: https://pivic.blog/blog/technical-writing/ https://pivic.blog/blog/technical-writing/
rocauc 3y ago
In your inference project example, what examples do you place in Getting Started vs common usage examples? In general, where is the best place for usage examples - alongside the methods they use, or in an independent section?
- zerojames 3y ago
  Good question! Getting Started is where I put the information someone needs to know to get started. This is based on two things: 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.html#indieweb_utils.get_h_app_item https://indieweb-utils.readthedocs.io/en/latest/indieauth.ht... [2]: https://supervision.roboflow.com/annotators/#supervision.annotators.core.BoundingBoxAnnotator.annotate 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) [3]: https://microformats.github.io/mf2py/#quickstart https://microformats.github.io/mf2py/#quickstart
kaycebasques 3y ago
"Advent of Technical Writing" is a great idea. Looking forward to reading the whole series. 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.
ulnarkressty 3y ago
Any ideas on how to help my engineer colleagues write good documentation that actually helps? Most of the problems that I see come from a lack of empathy - they assume the reader has previous knowledge about things that are only inside their head, so after reading the docs there's always the need for further clarification. 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...
- alpinisme 3y ago
  The key is not to focus on “what” needs documenting, but “how” someone will use your documentation: to get set up, to consume an api, to modify behavior, etc. If you write with the goal to help someone with X problem do Y to solve it, the empathy problem becomes a bit more tractable.
  - mjw1007 3y ago
    I see this advice a lot, and I think it's making the problem 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?".
    - alpinisme 3y ago
      Sure. But they can’t know whether it’s complete without answering the question, “have I given the reader all the info they’d need to solve their problem?” Edit: grammar
    - zerojames 3y ago
bloopernova 3y ago
This is interesting, thank you for writing it and sharing! 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.

93 points by zerojames 3y ago

Day two of this series is out, too): https://jamesg.blog/2023/12/02/navigation-links/ https://jamesg.blog/2023/12/02/navigation-links/ Further reading on technical writers and startups (knowing your audience, role, and more): https://jamesg.blog/2023/11/27/technical-writing/ 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.

pivic 3y ago
Perhaps a list of bibliography tips? Here's my five cents: https://pivic.blog/blog/technical-writing/ https://pivic.blog/blog/technical-writing/

rocauc 3y ago

In your inference project example, what examples do you place in Getting Started vs common usage examples? In general, where is the best place for usage examples - alongside the methods they use, or in an independent section?

zerojames 3y ago
Good question! Getting Started is where I put the information someone needs to know to get started. This is based on two things: 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.html#indieweb_utils.get_h_app_item https://indieweb-utils.readthedocs.io/en/latest/indieauth.ht... [2]: https://supervision.roboflow.com/annotators/#supervision.annotators.core.BoundingBoxAnnotator.annotate 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) [3]: https://microformats.github.io/mf2py/#quickstart https://microformats.github.io/mf2py/#quickstart

kaycebasques 3y ago

"Advent of Technical Writing" is a great idea. Looking forward to reading the whole series. 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.

ulnarkressty 3y ago

Any ideas on how to help my engineer colleagues write good documentation that actually helps? Most of the problems that I see come from a lack of empathy - they assume the reader has previous knowledge about things that are only inside their head, so after reading the docs there's always the need for further clarification. 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...

alpinisme 3y ago
The key is not to focus on “what” needs documenting, but “how” someone will use your documentation: to get set up, to consume an api, to modify behavior, etc. If you write with the goal to help someone with X problem do Y to solve it, the empathy problem becomes a bit more tractable.
- mjw1007 3y ago
  I see this advice a lot, and I think it's making the problem 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?".
  - alpinisme 3y ago
    Sure. But they can’t know whether it’s complete without answering the question, “have I given the reader all the info they’d need to solve their problem?” Edit: grammar
  - zerojames 3y ago

bloopernova 3y ago

This is interesting, thank you for writing it and sharing! 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.