Authoring documentation
This section describes the agreed practices on how to author documentation.
Language
Simple and Direct Language: Use simple, straightforward language. Avoid complex sentences and technical jargon that might confuse the reader.
Avoiding Polite Forms and Superfluous Words: Refrain from using words like "please," "kindly," or other polite forms that can make instructions seem optional. Keep language direct and to the point, as this helps in creating clear, concise, and unambiguous instructions. Such words, though polite, can potentially dilute the imperative nature of the instructions and lead to variability in how users interpret them.
Active Voice: Prefer active voice over passive voice. For example, "Click the button" instead of "The button should be clicked." This makes instructions clearer and more engaging.
Consistent Terminology: Use the same terms consistently throughout the manual. Changing terms for the same concept can confuse readers.
Positive Tone: Use a positive, helpful tone. Focus on what the user can do, rather than what they cannot.
Clear Definitions: When introducing new terms or concepts, define them clearly at their first mention.
Second Person Narrative: Use the second person ("you") to address the reader directly. This makes instructions more personal and easier to follow.
Brevity and Precision: Be brief but precise. Provide enough information to guide the user without overwhelming them with unnecessary details.
Use of Visuals: Accompany text with visuals where possible. This includes diagrams, screenshots, or icons to aid understanding. Do not reference the visuals as “Picture 1” or “Fig 1”, but structure the content to be always followed by an image to have a consistent natural flow. Note: much of the current documentation does use Figure references. This will be phased out as documentation is updated and should not be used on new content.
Avoid Ambiguity: Ensure that instructions and descriptions are unambiguous. Avoid leaving room for misinterpretation.
Naming and Formatting Conventions
Use full form of the CivicTheme product: CivicTheme
Use capitalised form of component name: Accordion, Accordion panel, Manual list
Use inline code for values:
Light,Dark,Top,Both,Expanded
Visuals
Make screenshots of the UI while being logged in as a role that can have access to the feature. DO NOT IGNORE THIS or users will be extremely confused.
Make screenshots of Admin UI using default Drupal theme Claro.
Do not include administrative elements like the top Admin Menu bar as this may not be installed on the consumer sites. Use navigation through pages instead.
Do not include screenshots of Admin UI pointing to the fields with numbered arrows and then referencing those numbers in text. Instead, use the text provided in the screenshot to reference elements - this will force to have smaller and more precise screenshots that users will find it navigate easier.
Make screenshots of the CivicTheme components front-end using only default colour scheme (that is the scheme of https://default.civictheme.io/). Using other colours schemes will confuse users.
Examples
Last updated