Hacker News new | ask | show | jobs
by WillAdams 99 days ago
https://diataxis.fr/

(originally developed at: 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)
2 comments
zenoprax 99 days ago
I've been trying to implement this as closely as possible from scratch in an existing FOSS project:

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.

link
ramses0 99 days ago 

    README => 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!

link