(possible) Goals / Use of the References
- Conceptual: to help to understand goals, principles & methods involved completing a process or task.
- Instructional: to learn how to complete a procedure (step-by-step instructions)
- (pure) Reference: To search for details when something has been forgotten (look-up) or when something unexpected happend (troubleshooting).
The hierarchy of the quality dimensions
Correctness (Richtigkeit): The technical correctness and completeness of the content is extremely important because it represents the reliable source for the users and staff members. The references have to be complete: Completeness does not mean that everything must be in there, but everything that is in there must be complete.(see also "Relevance")
Being Up-to-date (Aktualität): For essential content it is important that the documentation and the platform run synchronously. In this case, out-of-date content would mean incorrect content.
Communication (Vermittlung): Like every quality content the references are written in concise, clear and direct style. (see "Writing guide"). The user will easily find the information she is looking for, because the references are structured and searchable (internal & google).
The aspect of communication is primarily taken into account by distributing the issues to the different content formats (guides, exemples, refrences, help text) in a suitable manner and by preparing them appropriately for them.
- Relevance: (opponent: completeness) . Since the documentation should contain as complete information about the platform as possible,the appropriate selection of information for the application, such as is decisive in a guide, is behind the other quality dimensions. Content that is not directly related to the platform and its use should not appear in the documentation.
How to write references
The documentation will not be read carefully from start to finish. Rather, users will use the browser search or skim the page to orient themselves and quickly find what they are looking for. complete, accurate, reliable & unbiased. See also 7(?) Ws,- inverted pyramid (The most essential is always at the beginning. Keep sentences and paragraphs as short as possible.
Therefore the Website must be skimmable:
- make sure that the topics are structured clearly (and hierarchically)
- write meaningful headings
- organize the points: start with the most important or most basic information, then descend to less important and add more details
- write short body text with highlighting (bold) the main terms
- use bullet points and lists whenever possible (up to 7 points)
- use tables with meaningful headers
Therefore the Website must be searchable (internal & google):
- What keywords would the user use to search for this section?
- Use this keywords!
- Use the most important of this keywords in your heading
Language and Style
see also the Wiki in Tutorials.
When writing the references, keep the following points in mind:
- Use the right terms in a consistent way.
- Keep sentences and paragraphs as short as possible.(But vary the length of the sentences).
- Delete fluff words.
//to define the ##-Headings build the navigation use the keywords for the chapter (searchable) similarity in structure
// to define defining terms and concepts input/output explained
To be discussed
Who is the documentation addressed to?
- User & staff
Where do they come from? Directly from the platform, linked from the guides, linked from CS-Team....
How can I display different versions at the same time? Are there any cases where we need to have the old documentation online/archived? Continuous updating should initially be sufficient. If a platform update breaks compatibility, we can use the warnings to point it out.
We need a style guide for the references (for tables, headings, emphasizing)
How precise should we put links/anchors?= length of chapters
- Links should always be used when we refer to something else in our documents. But they should not be used excessively in a short entry.
- Archors should be used with a new entry/content.
How to adress the newbie and the expert? In the same way. There should be no differences in writing style. The content itself determines the level of the user.
How are they going to use it?
Relationship help text on the platform?
- Pure reference should not require any additional text to describe the relationship.
- Conceptual and instructional entries should contain relationship text if needed.
Do we need a glossary/index? Should not be the case with a complete reference.
How to establish a flow of information ? (roadmap café, announce channel)
Ideas for the editorial process
Who's writing? Alex W., Nyam, Peter, Pachi, Vita and Alex D
Create an issue ticket or change the content immediately when you see outdated content.
"immediately"contradicts the requirement of correctness.
The most important quality dimension "correctness" has consequences for the editorial processes, before a piece of content is published it has to be checked from a technical point of view (four-eye check).
Check the search queries for adjusting wording/content.
easy& known way to report errors
everyone has to know where to put what kind of content (guides, helpcenter, references).
last check with editing checklist