[HN Gopher] Advent of Technical Writing: Navigation Structure (D...
___________________________________________________________________
Advent of Technical Writing: Navigation Structure (Day 1 of 24)
Author : zerojames
Score : 36 points
Date : 2023-12-02 19:03 UTC (3 hours ago)
(HTM) web link (jamesg.blog)
(TXT) w3m dump (jamesg.blog)
| zerojames wrote:
| Day two of this series is out, too):
| 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/
|
| 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.
| rocauc wrote:
| 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 wrote:
| 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.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)
|
| [3]: https://microformats.github.io/mf2py/#quickstart
| kaycebasques wrote:
| "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 wrote:
| 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 wrote:
| 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.
| zerojames wrote:
| Having the engineer pair with someone who has never used the
| product before who also works in your org could help. I have a
| blog post coming up about this soon!
|
| 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.
___________________________________________________________________
(page generated 2023-12-02 23:00 UTC)