Key Principles¶

Collaborative Approach¶

Collaboration is one of F5’s core values. We believe that collaboration makes us, and our products, better.

Development Approach¶

Developing software documentation like code is an increasingly popular approach in the world of technical communication. At F5, this means that docs are:

• developed in the same repositories as the code (when feasible); and
• tested and reviewed following the same workflow as the code.

EPPO Topic-Based Approach¶

When you search for information on the Web, whether you use a search engine or follow a link, and you land on one of the billions of pages on the Web, that page, for you, is page one.

—Mark Baker, Every Page is Page One

The sentence above, from the introduction to the book Every Page is Page One, perfectly summarizes the ‘Every page is page one’ (EPPO) philosophy. EPPO is an information architecture that’s built from the bottom-up, relying on in-context links to direct readers to related content. It uses EPPO topics to organize and structure content. As Baker notes in ch6 section 3, EPPO topics should be able “to function alone, without dependence on a hierarchical structure” (the emphasis is ours). Rather, EPPO topics function independently by design but can also play a supporting role in a collection of documents.

You could think of a collection of Every Page is Page One topics like a box of toy cars. Each car is an independent toy in its own right. You can add a new car to the box or take an existing car away, but you still have a box of cars. And all the individual cars still work fine.

—Mark Baker, Every Page is Page One (ch 6.3)

We strongly recommend reading Every Page is Page One (it’s on Safari Books Online) but it you don’t have the time, you can read Neil Orint’s excellent synopsis on Hive.

What is “open source”, anyway?¶

“Open source” software is software for which the source code is freely available; users can redistribute and modify at will (with the appropriate credit given to the original source per its license/copyright, of course).

The OpenStack product suite constituted F5’s first foray into the open source community. The Application Services Integration iApp, AWS CloudFront templates, Container Connectors, and other projects followed suit soon after.

What if my project isn’t open source?¶

We use the term ‘open source’ throughout this documentation set, but that doesn’t mean that you can’t use the tools and practices described here if your project isn’t open source.

The OpenStack product and solution documentation is completely open source. In contrast, the Container Connector solution documentation is private, while the individual products’ documentation is open source. The Application Services Proxy’s code and documentation are both private. All three solutions use the practices and tools presented in this guide and publish their documentation to http://clouddocs.f5.com.

Basically, any cloud product (read: not BIG-IP or BIG-IQ) that develops docs like code can follow these guidelines and publish documentation on http://clouddocs.f5.com.

What is ‘solution’ documentation?¶

‘Solution documentation’ consists of user guides, tutorials, troubleshooting, etc. This is the core documentation set that the user consults to learn how to accomplish a specific goal. The following rules apply to all solution documentation:

• Solution docs must be goal-oriented (i.e., each document should tell the user how to accomplish a specific goal).
• Solution docs should not explicitly duplicate information provided at the product level. Instead, (following the EPPO model) we use links to direct the user to the place where s/he can find the desired information.
• Solution docs use continuous deployment.

Solution documentation may live in a specific project’s docs/ directory or it may be part of a separate, docs-only project repo. The general rule of thumb is that if the solution comprises multiple products, create a separate solution docs repo. This allows us to present docs in ways that make sense to the customer without the limitations imposed by individual projects.

Good examples of solution docs repos are f5-ci-docs and f5-openstack-docs. [1]

What is ‘product’ documentation?¶

‘Product’ documentation contains all reference information for a specific product, including (but not limited to) the following:

• all config options
• cli args
• api
• syslog messages

Product documentation lives in the project repository’s docs/ directory. The primary file is a docs/README.rst (required for content to render correctly in GitHub/GitLab). We import the content of the README file into the docs/index.rst file when we build the docs; the index file serves as the product’s home page on clouddocs.f5.com.

The k8s-bigip-ctlr, marathon-bigip-ctlr, and asp project repositories all provide good examples of product doc READMEs and config examples.