In technical documentation, we often speak of "structured content". I think this is a fancy way of saying "predictable" or "knowing what you're going to get", as opposed to free-form text.
Structured vs. unstructured content
To highlight the difference, compare a dictionary or phone book to a narrative book, for example, an instructional book on programming.
Entries in a dictionary or phone book are in alphabetical order, and are approximately of the same length.
In a narrative book, chapters or sections are far less uniform. Their length and scope can vary greatly. The chapters are arranged in an arbitrary order determined by the writer, which the reader may or may not find intuitive to navigate.
Structuring content presumably means making it more like dictionaries and less like narrative books.
Documentation frameworks and content types
Documentation frameworks such as DITA and Diataxis provide a set of predefined rules for structuring content.
What strikes me as odd about both frameworks is that they categorize content by type, such as concept, tutorial, reference, or explanation, an arbitrary dimension of little value to the reader. No one reads docs thinking, "I need a concept."
If the objective of structuring content is to make it predictable, I don't think either framework achieves this.
Alphabetical ordering
Alphabetical ordering would also not be meaningful. Most terms are product-specific and unknowable for new users, especially in software. You could place an entry for "content slice" under C, but new users wouldn't know where to look for it because they don't yet know what that is.
Reverse chronological ordering
With all that in mind, I'm leaning toward structuring documentation by date, sorted in reverse chronological order, like the news.
Across multiple software products, I've seen the same pattern in documentation: new features, delivered with a specific release on a specific date, and everything else. Let's call the latter behavioral notes.
I would put the new features at the top, sorted by date released, followed by the behavioral notes, sorted by date documented. The reason for the latter is that such items are often reported long after the behavior was first introduced, and that date becomes less important over time.
Conclusion
In conclusion, I'm proposing to structure documentation by date, a dimension readers already know and understand. It's hardly perfect, but less broken than arbitrary content types.
Top comments (0)