A Framework for Writing Better Documentation (documentation.divio.com)
recommended by 3 users | 2021 | 637 points by omginternets | code quality | original thread |
3 users recommended this thread. What they said:
KajMagnus Feb 5, 2021 | on: Disqus, a dark commenting system | context

Talkyard Blog Comments, https://talkyard.io/blog-comments

(I'm developing it. Open source: https://github.com/debiki/talkyard. Not yet so well documented — soon time to add more docs, ... as per this nice discussion: https://news.ycombinator.com/item?id=26002656 )

alexrustic Apr 12, 2021 | on: Show HN: My attempt to demystify Python GUI development | context

Thank you ! A quick hint from HN is valuable !

I definitely need to quickly build a website to summarize the project's ecosystem. The documentation was more messy months ago. I discovered a framework for writing better documentation [1] which made things less messy.

> We certainly need a practical way to make Python desktop GUI apps

You can take a look at Dresscode [2]. This is my latest project [3]. It aims to quickly create a desktop application without prior knowledge of Tkinter. Also, it's suitable to existing codebases (no need to alter your existing codebase). If Pyrustic Framework is C, Dresscode would be Python !

[1] https://news.ycombinator.com/item?id=26002656

[2] https://github.com/pyrustic/dresscode#readme

[3] https://news.ycombinator.com/item?id=26731674

infogulch Oct 22, 2021 | on: Docs for Developers: An Engineer’s Field Guide to Technical… | context

I like linking to this site [0], the "The Grand Unified Theory of Documentation" that describes four categories of documentation that fill out a 2D space of potential docs value: the practical steps <-> theoretical knowledge dimension, and the useful when studying <-> useful when working dimension.

    * Tutorials - Learning-oriented -  (practical/studying)
    * How To Guides - Problem-oriented - (practical/working)
    * Explanations - Understanding-oriented - (theoretical/studying)
    * Reference - Information-oriented - (theoretical/working)

It passed through HN ~9 months ago [1], where kaycebasques stated, "I think the key breakthrough with Divio's framework is getting authors to think about docs in terms of desired goals and outcomes: learning-oriented, problem-oriented, etc."

[0]: https://documentation.divio.com

[1]: https://news.ycombinator.com/item?id=26002656