Best practices for Open Horizon documentation

Grammar

• Copy should be written in the third-person, active voice
• Identify and replace "and/or" and related compound joining word/phrases

Styles

• Identify and replace Latin-based content (for example: "i.e." should be "that is"; "e.g." should be "for example"; "etc." should be "and so on")
• Headlines and titles should only have the first word and proper nouns capitalized
• Sequences and steps should be enumerated ... using numbered points for each
• Identify and replace directional content
• Identify and replace visual cues
• Identify and replace jargon and cultural references

Conventions

• Copyright notice should span from start year through current year and be updated every January
  • Current year example: Copyright Foo, 2020
  • Second year example: Copyright Foo, 2020 - 2021
• When referring to persons or groups who use Open Horizon, do not use the words "customer" or "user". Instead, use "adopter".

Modules and components

Information Architecture

• Personas will be created (ex. app dev, model dev, admin, DevSecNetOps, architect)
• User journeys will be identified based on personas
• Breadcrumbs will be used to allow section identification and navigation within a section
• Titles will reflect the page content
• og-meta tags will be used for: social media sharing, SEO optimization, machine-readability
• Jekyll theme will be updated for usability, accessibility, responsive web design (something like CDS, ideally)

Re-usability

• All proper names and trademarks will be inserted via variables
• Environment- and feature-specific sections will be surrounded by conditional rendering tags
• Headers, footers, navigation will be included at page generation and not embedded

Contributions

• Always open an issue before beginning to contribute. No bare PRs, please.
• Try to use the appropriate issue template. If unsure, just ask in the chat room.
• Make issues as atomic as possible. Do not put unrelated bugs into a single issue.
• When working on an issue, follow the standard process of:
• • Forking the repo
• • Creating a local branch with the issue in the format issue-###
• • Commit often, each time with the -s or --sign-off flag
• • Test your committed code before creating a PR. If unsure how to test, ask in the chat room.
• • Create the PR by prefixing the title with Issue: ## - <title of PR less than 72 characters>
• • Label the PR with the same labels as the issue
• • "at" mention one or more Maintainers in a PR comment, and assign it to them if you can.
• • Link the PR to the issue.
• • Be prepared to answer any questions and make any changes.

NOTE: Most of this content should be moved to the project profile section instead of residing in a single repository.