I’m looking for some inspiration on technical product documentation in the DevTools space (think cloud platforms, CI/CD, etc.)
Airship, formerly Urban Airship, i think.
a few years ago i was helped to build out a Sphinx-based search feature, integrate it into a Pyramid-based app, and something UA were doing made me want my app/docs to look/act like theirs
part of it was the search, part of it was the comprehensiveness, part of it was the magically-appearing in-page #anchor links when you'd mouseover an <H>-type header element so that you could easily refer to a section of a page -- something which i feel like is obviously crucial to useable docs, but rarely exists in real life, and part aeshetics.
a quick glance just now seems they still have docs, tho i guess most established company doc sites would look good and generally be high-functioning these days. i suspect more of them were built from scratch back in the day, but not sure -- it's prob difficult for the docs vendors to keep up with integrating api tools, etc.
An official guide on integrating the Raspberry Pi RP2040 microcontroller into one’s own circuit design. Essentially a series of worked examples that touch on pretty much every hardware feature of the chip, with a good amount of advice transferable to other microcontrollers. Provides steps and justifications. The RP2040 datasheet is equally fantastic: straightforward wording, minimum abuse of passive voice commonly seen in microcontroller literature, and accompanying C/asm examples.
[0]: https://datasheets.raspberrypi.com/rp2040/hardware-design-wi...
If you're looking for a system that looks as good, mkdocs (https://www.mkdocs.org/) with the mkdocs-material theme (https://squidfunk.github.io/mkdocs-material/) can get you quite close!
> Digital Equipment Corporation noted in their 1983 internal documentation guidelines that user documentation should be written first — not last as is traditionally done — because the user documentation is an excellent way to debug the design of a system or a program. “If a writer finds it difficult to document a system, the problem is probably the system not the writer. Holes in design, obscure constructions, and apparent contradictions become starkly visible in the documentation.”
(From book: Writing better computer user documentation, 1990)
I don't like Python docs where it ends up on long winded explanation for specific cases but does not cover all arguments, or only mention some in passing.
I would compare it to having a recipe vs a list of ingredients. Both are useful but I can't just cook if you just give me a list of ingredients without instructions.
And then you have NestJS that does neither so you just get a random piece of information but missing 75% of instructions and no good API doc.
Nicely done approach to de-complexifying a fairly complex schema.
Wish I could think of an example off the top of my head though, but nothing is springing to mind.
Was doing stuff with (the official) SQLite extensions a few weeks ago, and the docs didn't really cover some of the things I was after at the time. Not the end of the world, just a bit frustrating.
Am I missing something?
Asking for assistance and giving feedback just gets completely ignored now, whereas when we first created our account the support staff were very keen + helpful.
Not sure what's changed, but it's not good now. :(
Don't get me wrong, Cloudflare does a nice job. So many vendors today don't have a documentation forward perspective. I recently worked at a startup that had basically no documentation and found that the product was poorly designed and did not work as they advertised it. At this point in my career one of the first things I'm looking for when considering a product or organization is good documentation. Skipping that validation has almost always bitten me. A lack thereof seems to indicate taking a shortcut and broader issues that may be lurking.
