OpenWeave Documentation Style Guide
OpenWeave documentation lives in two locations:
- GitHub — All guides and tutorials across the complete OpenWeave organization.
- openweave.io - OpenWeave news and features, educational material, API reference, and all guides and tutorials found on GitHub.
All documentation contributions are done on GitHub and mirrored on openweave.io, and will be reviewed for clarity, accuracy, spelling, and grammar prior to acceptance.
See CONTRIBUTING.md for general information on contributing to this project.
Place all documentation contributions in the appropriate location in the
/doc directory. If you are unsure of the best location for your contribution, let us know in your pull request.
For consistency, all document links should point to the content on GitHub, unless it refers to content only on openweave.io.
The text of a link should be descriptive, so it's clear what the link is for:
For more information, see the OpenWeave Style Guide.
Use standard Markdown when authoring OpenWeave documentation. While HTML may be used for more complex content such as tables, use Markdown as much as possible. To ease mirroring and to keep formatting consistent with openweave.io, we ask that you follow the specific guidelines listed here.
Note: Edit this file to see the Markdown behind the examples.
Command line examples
Feel free to use either
% to preface command line examples, but be consistent within the same doc or set of docs:
$ git clone https://github.com/openweave/openweave-core.git % git clone https://github.com/openweave/openweave-core.git
If you need use a full terminal prompt with username and hostname, use the format of
For example, when logged into a Docker container, you might have a prompt like this:
Or in a Happy node, you might have:
The Device Manager prompt should also be used if necessary. It should start with
weave-device-mgr and end with
> to ensure it's properly imported into openweave.io:
weave-device-mgr > help
This includes verbose Device Manager prompts, such as when connected to another node:
weave-device-mgr (18B4300000000004 @ fd00:0:fab1:6:1ab4:3000:0:4) > ping
Commands and output
All example commands and output should be in code blocks with backticks or indented:
code in backticks
Code blocks in step lists
When writing procedures that feature code blocks, indent the content for the code blocks:
$ git clone https://github.com/openweave/openweave-core.git $ cd openweave-core
More about step one.
Step two, do something else.
Use backticks for
inline code. This includes file paths and file or binary names.
In code examples, denote a replaceable variable with curly braces:
Step header numbers
If you want your headers to render with nice-looking step numbers on openweave.io, use level 2 Markdown headers in this format:
## Step 1: Text of the step ## Step 2: Text of the next step ## Step 3: Text of the last step
See the OpenWeave + Happy Cross Network Multicast Inet Layer HOWTO for an example of this:
Use a blockquote
> with one of these callout types:
Note: This is something to be aware of.
Caution: The user should be careful running the next command.