Write a very bad introduction to structuring docs #10063
Conversation
I got motivated to write this, but struggled to figure out what to say in a clear way.. Leaving this in a draft for another day.
| Structuring your documentation is an important part of the authoring process. | ||
| It's important to think about the reader of the documentation, | ||
| since they are the primary user of documentation. |
There was a problem hiding this comment.
I'd go even further here?
We have the :term: entry for discoverability that might be handy as well: https://docs.readthedocs.io/en/stable/glossary.html#term-discoverability
| Structuring your documentation is an important part of the authoring process. | |
| It's important to think about the reader of the documentation, | |
| since they are the primary user of documentation. | |
| A documentation project's ultimate goal is to be read and understood by a reader. | |
| Readers need to be able to :term:`discover <discoverability>` the information that they need. | |
| Without an intuitive structure, | |
| readers either won't find information that they need or get frustrated on the way. | |
| Having a structure in mind can happen from the very beginning of a documentation project. | |
| Changing and adapting your structure is often also necessary. | |
| .. tip:: | |
| Even if your documentation already has a structure, | |
| we invite you to keep reading. | |
| Changing a documentation structure is hard work, | |
| but the rewards are big. |
(can write a bullet list of benefits of a good Diátaxis structure as a motivation for people to continue learning about the Framework?)
|
|
||
| One of the largest benefits of a good structure is that it removes questions that keep authors from writing documentation. | ||
| Starting with a blank page is often the hardest part of documentation, | ||
| so anything we can do to remove this problem is a win. |
There was a problem hiding this comment.
This is super important stuff! I think this could be great for the first section: "Why documentation needs structure"
| Recommendations for process | ||
| --------------------------- |
There was a problem hiding this comment.
| Recommendations for process | |
| --------------------------- | |
| Choosing a structure | |
| -------------------- | |
| Good news! | |
| You don't have to invent all of the structure yourself, | |
| since a lot of experience-based work has been done to come up with a universal documentation structure. |
Maybe we should also change our example projects to have a Diátaxis skeleton? :)
|
This is definitely an introduction and explanation that we should have. Love that you've started this work 💯
I think it looks good. I tried to add some suggestions, thinking that it will get there soon. I'd like to have an over-all Explanation section called something like "Best practice and methodology". Because this is tasty to me as a reader. In there, we have several how-to guides on best practice that we can introduce and then we can add this exact article -- but in a framing where it doesn't have to stand alone, but it will be supported by other things we have written in the same department. Another example: Our current work with translation workflow can also lead to an article that deals with methodology and structure - in addition to the articles that deal with technical tools and how-to of translation work. It would be great to be able to write an explanation and that it can land in a clearly defined explanation sub-level. |
|
This wasn't bad at all btw ❤️ Continued the work here: #10071 Hoping it's fine to close this, will be happy to pass back the writing pen to you @ericholscher, just gonna wrap up the overall Explanation structure to fit it. |
I got motivated to write this,
but struggled to figure out what to say in a clear way..
Leaving this in a draft for another day.
📚 Documentation previews 📚
docs): https://docs--10063.org.readthedocs.build/en/10063/dev): https://dev--10063.org.readthedocs.build/en/10063/