4 ms·
https://diataxis.fr/ https://diataxis.fr/ (originally developed at: https://docs.divio.com/documentation-system/ https://docs.divio.com/documentation-system/)
by WillAdams 8mo ago
https://diataxis.fr/ https://diataxis.fr/
(originally developed at: https://docs.divio.com/documentation-system/ https://docs.divio.com/documentation-system/) --- divides documentation along two axes:
- Action (Practical) vs. Cognition (Theoretical)
- Acquisition (Studying) vs. Application (Working)
which for my current project has resulted in:
- readme.md --- (Overview) Explanation (understanding-oriented)
- Templates (small source snippets) --- Tutorials (learning-oriented)
- Literate Source (pdf) --- How-to Guides (problem-oriented)
- Index (of the above pdf) --- Reference (information-oriented)
- zenoprax 8mo agoI've been trying to implement this as closely as possible from scratch in an existing FOSS project: https://github.com/super-productivity/super-productivity/wiki https://github.com/super-productivity/super-productivity/wik... Even with a well-described framework it is still hard to maintain proper boundaries and there is always a temptation to mix things together.
- ramses0 8mo agoREADME => AGENTS.md HOWTO => SKILLS.md INFO => Plan/Arch/Guide REFERENCE => JavaDoc-ish I'm very near the idea that "LLM's are randomized compilers" and the human prompts should be 1000% more treated with care. Don't (necessarily) git commit the whole megabytes of token-blathering from the LLM, but keeping the human prompts: "Hey, we're going to work on Feature X... now some test cases... I've done more testing and Z is not covered... ok, now we'll extend to cover Case Y..." Let me hover over the 50-100 character commit message and then see the raw discussion (source) that led to the AI-generated (compiled) code. Allow AI.next to review the discussion/response/diff/tests and see if it can expose any flaws with the benefit of hindsight!