httpyac VS diataxis-documentation-framework

Website: httpYac Git: https://github.com/AnWeber/httpyac

There's also https://httpyac.github.io/ which has both standalone CLI and VS Code extension versions – might be interesting to explore.

Here is the github repo for httpyac [1]. Not sure why it's not part of the httpyac org that hosts the site.

[1] https://github.com/AnWeber/httpyac

Not OP but I think you have the right intuition in making a difference between using the app / contribute to the app. You may want to read https://diataxis.fr/ which elaborate on this idea and add another dimension (action / cognition) to this.

I came here to say something like "This is a joke, right?" Not to be snarky, but because I just assume everyone throws the Inevitable Looming Tool at docs, especially where resource is scarce.. but this point has already come up and I suppose there is some truth in the idea that folks detect AI and are often put off by it - but while I think that's true in creative/blog pieces, is it really true in formal docs? For me that is in the same column as cancer cures, gene comprehension, room temperature fusion wrangling etc. - the 'lets-get-AI-onto-it-pronto' column...

Anyway, my vapid observations aside, I have a couple of related questions:

- I too would be willing, even keen, to contribute to good documentation of FOSS projects that need it and that I am interested in - a huge barrier to me is that a person needs sufficient understanding to really contribute, don't they? To the point that you pretty much need to get into the code quite deeply or else endlessly pester committers to explain how it works? OK, I am generalising, but it seems valid in the main. A while ago, I observed on a relevant list that the libvirt documentation of how to take qemu snapshots was amazingly fragmented, inconsistent and out of date and this led to comments that I should step up and produce some PRs - but my whole point was that this sh1t is hard to understand without very good docs! I would barely know where to start and I would be very hesitant about making definitive statements...

- As for improving doc structure - and this is a serious consideration as soon as you sit down to think about this stuff - I came across and adopted the https://diataxis.fr/ framework a few years ago.. I have to say the uptake among my co-workers has been dismal. Can anyone suggest doc frameworks or approaches that are more motivating, have less friction, whatever?

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)

API documentation / types / signature is just one of the four types of documentation[1] that every service and library should ship. The other three are for telling people the things that code cannot tell you. The OP is arguing that the only "docs" you need are "how do I call this", not "what does this do", or "what do I do with the results", among plenty of others.

So no, what the author should be writing is "Ship Types and Docs".

[1] https://diataxis.fr/

What is the new way in which manuals should be written?

I've been trying via Literate Programming:

http://literateprogramming.com/

and applying the concepts of:

https://diataxis.fr/

(originally developed at: https://docs.divio.com/documentation-system/) which divides documentation along two axes:

- Action (Practical) vs. Cognition (Theoretical)

- Acquisition (Studying) vs. Application (Working)

resulting in a matrix of four things

- Tutorials

- How-to Guides

- Explanation (of the code)

- Reference (of the code)

which seems to be working well for my current project: https://github.com/WillAdams/gcodepreview/blob/main/gcodepre...

What you describe sounds a lot like Diátaxis[1], which is a strategy for writing and organizing technical documentation. It categorizes docs into one of four categories: tutorials, explanations, how-tos, and references.

Category is derived from a fairly simple heuristic: whether the content informs action or cognition, and whether the content serves the reader’s application or acquisition of a skill[2]. I’m a fan and it’s simple enough that most anyone can learn it in an afternoon.

1. https://diataxis.fr/