4 ms·
Brilliant. Only on HN will get ask a question and get an answer from the author of the original document. Completely freakin' cool. While I have you, I'd like
by dont__panic 4y ago
Brilliant. Only on HN will get ask a question and get an answer from the author of the original document. Completely freakin' cool.
While I have you, I'd like to ask a follow-up question that's always bothered me. How do you make documentation structured this way "beginner friendly"? It seems to me like advanced users love this kind of segmentation of content, but it's tough as a new user to find relevant sections, both for getting an initial understanding and then for problem solving for specific tasks early in their user journey.
Do you have any tips for structuring documentation in such a way that you can follow the Diátaxis 4-type model while also making content discoverable? Examples would be great as well. Just tying to draw inspiration for a project I'm currently working on.
- DanieleProcida 4y agoI'd say it's the other way round. If you follow the Diátaxis model, and keep thinking about your material according to its principles, you will find that the structure starts to emerge. For an example, consider https://brachiograph.art https://brachiograph.art. It's pretty imperfect documentation, but the needs of the newcomer are answered in the tutorial, along with the clear instruction: Start here. Everything else is laid out in the contents and findable there.