3 ms·

Smaller docs (and more of'em) throws up the problem of findability. The author lists the usual "fixes" but I do not find it convincing. This is where I'd expec

Smaller docs (and more of'em) throws up the problem of findability. The author lists the usual "fixes" but I do not find it convincing. This is where I'd expect an A.I.-powered tech support chat system to help. Then smaller-is-better might really work well. Just be sure to supply some helpful+necessary context (intro/outro) when directing me to the mini doc. And if there's going to be A.I. then it might help with the items on the author's list too (doc organisation, doc linking, doc hygiene).

hinkley 2y ago
Smaller docs result in more introductory sentences and people are worse at writing introductory sentences than they are at writing documentation. I just lost an argument with as OSS maintainer who insisted that the opening paragraph to an important doc had to remain technically precise despite being completely impenetrable to most of the users who would land on it (likely entry point from google, shortly after picking up the library).
- euroderf 2y ago
  There's a concept called "Every Page Is Page One": https://idratherbewriting.com/trends/trends-to-follow-or-forget-every-page-is-page-one.html https://idratherbewriting.com/trends/trends-to-follow-or-for... An attempt to meet the needs of people following search engine links right into the middle of documentation. This is where I wonder if an A.I. could provide missing introductory context, based on the conversation that got you to the doc.
  - hinkley 2y ago
    That was effectively the problem. There are pages that describe concepts but search engines take you right to the API which introduces related jargon words that are neither defined nor hypertext. But I fear this is a bridge too far for a domain that didn’t bother making DevEx a thing until a few years ago.
    - euroderf 2y ago
      Good point about jargon. So every page needs a link to (or a listbox of) glossary.
      - hinkley 2y ago
        Or just use industry standard words and introduce the jargon deeper down. Like in function arguments.

hinkley 2y ago

Smaller docs result in more introductory sentences and people are worse at writing introductory sentences than they are at writing documentation. I just lost an argument with as OSS maintainer who insisted that the opening paragraph to an important doc had to remain technically precise despite being completely impenetrable to most of the users who would land on it (likely entry point from google, shortly after picking up the library).

euroderf 2y ago
There's a concept called "Every Page Is Page One": https://idratherbewriting.com/trends/trends-to-follow-or-forget-every-page-is-page-one.html https://idratherbewriting.com/trends/trends-to-follow-or-for... An attempt to meet the needs of people following search engine links right into the middle of documentation. This is where I wonder if an A.I. could provide missing introductory context, based on the conversation that got you to the doc.
- hinkley 2y ago
  That was effectively the problem. There are pages that describe concepts but search engines take you right to the API which introduces related jargon words that are neither defined nor hypertext. But I fear this is a bridge too far for a domain that didn’t bother making DevEx a thing until a few years ago.
  - euroderf 2y ago
    Good point about jargon. So every page needs a link to (or a listbox of) glossary.
    - hinkley 2y ago
      Or just use industry standard words and introduce the jargon deeper down. Like in function arguments.