Simon Willison’s Weblog

Items tagged documentation in Aug

Filters: Month: Aug × documentation ×

Design Docs at Google. Useful description of the format used for software design docs at Google—informal documents of between 3 and 20 pages that outline the proposed design of a new project, discuss trade-offs that were considered and solicit feedback before the code starts to be written. # 7th August 2020, 4:31 pm

Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference. Each of them requires a distinct mode of writing. People working with software need these four different kinds of documentation at different times, in different circumstances—so software usually needs them all.

Daniele Procida # 3rd August 2019, 8:29 am

The subset of reStructuredText worth committing to memory

reStructuredText is the standard for documentation in the Python world.

[... 1183 words]

Honeycomb changelog (via) Too few hosted services have detailed user-facing changelogs. This one from Honeycomb (a metrics, tracing and observavility platform) is a particularly great example. I especially like the use of animated screenshots, something I’ve been evangelizing pretty heavily recently for internal communication at work. # 25th August 2018, 3:12 am

Django documentation (for 1.0). The documentation refactor is in: the docs for the upcoming 1.0 release have been tidied up, rearranged and ported to a new documentation system based on Sphinx (the Python documentation toolkit, NOT the full-text search engine). The URL has also changed to # 24th August 2008, 10:49 am

GeoDjango Documentation. Merged to Django trunk a few hours ago. The tutorial isn’t there yet, but the rest of the docs are worth exploring. # 5th August 2008, 11:06 pm

Thoughts on (and pics of) the original Macintosh User Manual. “[I] was struck by how it had to explain a total paradigm shift in interacting with computers”. # 30th August 2007, 5:32 am

The Python docs have been redesigned for 2.6. They’re beautiful. The docs for a module are on a single page now (rather than splitting over multiple pages), they’ve added unobtrusive permalinks to individual sections and the whole thing is built on ReST rather than LaTeX. # 18th August 2007, 12:39 pm