-
Notifications
You must be signed in to change notification settings - Fork 102
Style Guide
Language in the documentation should be as clear and jargon-free as possible (commonly-used terms in Omeka do not count as jargon; see Terminology below)
Explain every possible step, even the ones which seem obvious. It is better for users to skip a step they've already completed than be confused by a leap they can't follow.
Break long tasks into small paragraphs and/or lists. If using ordered lists, be sure to check and make sure the numbering and depth of each item is preserved.
Have someone proofread your documentation when possible. For a true test, find someone who has not interacted with the feature/plugin/theme and have them use your documentation to learn how to use it.
Describe buttons, etc, using both color and location. Be mindful of users who are colorblind or use screen readers when describing functions.
Be robust in creating sections, using headers (see below) to break them out. Headers will show up in the sidebar navigation of the documentation and allow us to link to a specific part of a documentation page.
Ways to break out sections include:
- Plugin configuration and use
- A section for each tab in a functionality
- Sections for creating, adding, editing, and deleting a thing.
- left-hand navigtion: describes the admin-side menu, where Items, Collections, Etc are found.
- top navigation menu: describes the navigation menu of the administrative side of Omeka which includes Plugins, Appearance, etc.
Links or buttons described in the text should be in quotation marks (ex. "Save Changes" or "Reset Navigation"). Options for Plugin configuration can also be given in bold or italics if each option serves as the beginning of a list item or paragraph. (ex. Appearance Settings' display settings
Capitalization of labels, links, and settings should exactly match how they appear in Omeka.
Headings Start internal headings with H2 (##). Use H3 and H4 as appropriate.
Links should be relative to the root or the present folder
In general, documentation images should be stored in the doc_files directory. Images for plugin documentation go in the Plugins directory within the doc_files directory.
In general, images should be placed below the text they illustrate.
Name images something which relates to the purpose of the image. exhibitpageex is more useful than zxcn2983 or screenshot4.
When adding images to Omeka documentation, be sure to make use of the area between the brackets ( ) to provide a useful image description.