Skip to content

Best practices for Open Horizon documentation

Jump to bottom
Joe Pearson edited this page Mar 10, 2022 · 18 revisions

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
  • Mark up all external links with a target and externalLink className:
[Kubernetes debugging](https://kubernetes.io/docs/tasks/debug-application-cluster/debug-application/){:target="_blank"}{: .externalLink}

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.

Clone this wiki locally