F5 Docs Like Code Style Guide

Welcome to the F5 style guide for docs like code projects. This guide supports and supplements the official Unified Style Guide.

Introduction

The F5 docs like code style guide establishes the philosophy, tools, styles, and processes used to produce documentation following docs-like-code methodologies.

The content provided here should help ensure consistency and quality in projects for which multiple contributors – technical writers, engineers, PM, & GSS alike – author documentation.

If you’d like to provide feedback, report a bug, and/or contribute to this guide, please open an issue or fork the project repo in GitLab.

Mission Statement

We follow the “treat docs like code” ethos:

  • Docs are part of the development workflow, created in parallel with code development and testing.
  • Docs development uses the same Version Control System (VCS) as the product code and follows the same workflows.

This effort is collaborative and continually evolves to embrace new technologies and best practices. Above all, we strive to provide clear, concise content that is easily accessible to, and usable by, our customers.

See also

General guidelines

  • Review this style guide if you’re unsure how to begin, what tools and processes to use, etc..
  • Be clear.
  • Be familiar. Explain a concept in the same way you would when speaking to a colleague.
  • Don’t get bogged down in details; write for the 80% use case and address corner cases if/when necessary.
  • Include the code example in your docs/_static/config_examples directory in other docs using literalinclude.
  • When you use literalinclude, provide a :download: link so the user can download the file.

Version Control: Committing and Pull Requests

  1. Commit your documentation changes as you work.
  2. Fetch and rebase your work against the source (e.g., upstream) regularly.
  3. Squash your commits before opening a pull request.
  4. Include clear commit messages that describe what you’ve done.
  5. When opening a pull request, provide a clear summary of what changes/additions you’ve made.
  6. Assign your pull request to the appropriate person and be sure to @ mention your docs reviewer!