mjahoda
commented
3 months ago Hi @emteelb This is a very good point. Because the majority of contributors to the mod-docs guide were already at least a bit familiar with the key terms, we easily overlooked this drawback. We'll discuss the issue at the next steering committee meeting, and I believe we'll agree on addressing it as you suggested. Thank you very much for your constructive feedback!
emteelb
First, reading this documentation has been very helpful and enlightening and gives me some ideas to improve my own documentation work. So thank you to the authors and maintainers. I am happy to have stumbled across this.
That said, I found it difficult to get into the documentation because the introduction uses three jargon terms (user story, assembly, and module) that aren't defined in the "What modular documentation is" section itself. Only at the section's end in an additional resources subsection is there a link to where these terms are defined.
To a new reader, this is confusing because the documentation starts using technical terms that it hasn't described yet to try to describe what modular documentation is. How can an unfamiliar reader be expected to follow along with understanding? The documentation is basically asking a new, unfamiliar reader (me, for example) to read an entire section with suspended belief because of undefined key terms, get to the end of the section, jump to a link where the key terms are defined, then reread the original section having gained an understanding of the key terms.
It would be better to define those three key terms in the introduction itself, before proceeding to use them.
I am willing to help out here if wanted.