-
Notifications
You must be signed in to change notification settings - Fork 80
Documentation guidelines
Documentation should be written in (Github-flavored) Markdown.
Use clear language, free of (non-Omeka) jargon.
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. Do not assume any prior knowledge on the part of the user for this documentation (See the Peanut Butter and Jelly classroom exercise for an example of exact instructions).
Break longer tasks up into short paragraphs or lists.
Use illustrative images when needed, especially to indicate which button or link users should engage with.
New page files should be saved in the appropriate folder, corresponding to the structure of the left-hand navigation on the Omeka S Admin dashboard. Pages which do not relate to a subset of the left-hand navigation should go in the main level of the documentation directory.
Use the language found in the Glossary in the documentation.
Section headings should start with H2 (##) and go down to H4. Create sections where it is logical in the documentation structure; they will appear in the left navigation of the documentation (see Pages Management for an example of extensive section use)
Links
Links should be composed as relative to the current file.
Images
Images for a file go into the files director of the directory in which the file sits (so, for content files, images go into the contentimages directory).
Commit changes to the master branch of this repository. If you have significant changes (structural overhauls, unreleased modules or functionality), create a branch in which to work until those changes are ready for publication.
Once you have committed your changes to this repository, alert one of the developers so that they can push the changes to the site.
Navigation is managed through the mkdocs.yml file.