OpenStack-SDK-PHP/UserFacingDocumentation

Proposed Directory Structure

At the top-most level (i.e., right under the project root directory), there will be two directories related to user-facing documentation: doc and examples. The doc directory will contain the actual user-facing documentation while the examples directory will contain standalone PHP scripts for individual tasks (such as creating a container). The documentation in the doc directory will reference the example scripts in the examples directory, letting the user download standalone, working versions of PHP code for examples shown in the documentation.

The doc directory will contain a user-guides subdirectory. This will contain Getting Started Guides and Complete User Guides for each OpenStack service. It will also contain a _common directory for any shared documentation snippets to be included from other documentation (for instance, documentation on authentication).

The examples directory will also contain subdirectories. These subdirectories will mirror those under doc/user-guides.

 doc/
   user-guides/
     _common/
     compute/
       getting-started.rst
       complete-user-guide.rst
     object-store/
       getting-started.rst
       complete-user-guide.rst

 examples/
   compute/
   object-store/
     create-container.php

Getting Started Guide Structure

There will be exactly one Getting Started Guide per OpenStack service (excluding Identity, perhaps?). The goal of this guide is to let the reader start using that service in a few minutes. As such, it should guide the user through a common and short use case for that service.

Finally, at the end of a Getting Started Guide, there should be a link to the Complete User Guide for the same service. This gives the reader a next step instead of a dead end.

Sample getting-started.rst (abbreviated)

First, authenticate:

 code snippet 1

Then, do XXX.

 code snippet 2

As a result of XXX, you will get so and so.

Then, do YYY.

 code snippet 3

Then, do ZZZ.

 code snippet 4

[Download standalone PHP script for this example] -> links to examples/compute/getting-started.php

Next Steps: There's more you can do with QQQ service. To find out, read the [complete user guide] next.

Complete User Guide Structure

There will be exactly one Complete User Guide per OpenStack service (excluding Identity, perhaps?). The goal of this guide is to let the reader browse through a comprehensive set of use cases for the service. Organization of this guide will be more complex than that of the Getting Started Guide. Primarily, the guide should be organized such that it covers the common use cases first. This might not be straightforward, though, since other factors will also come into play: it might be helpful to introduce readers to concepts first, before delving into specific use cases that use those concepts; similarly, it might make sense to group use cases around the components of the service so there is less context-switching for the reader.

Finally, it is possible that a reader arrives at this guide without reading the corresponding Getting Started Guide first. Therefore the content in the Getting Started Guide may be duplicated in the Complete User Guide. Avoid the temptation to link the reader to the Getting Started Guide. Consider embedding it if possible instead. This gets the reader all their content on one page (i.e. no further clicks) as well as keeps it easily searchable (using Ctrl/Cmd-F for instance).

Sample complete-user-guide.rst

First, authenticate:

 code snippet 1

Common use case #1

 code snippet 2

[Download standalone PHP script for this example] -> links to examples/object-store/create-container.php

Common use case #2

 code snippet 3

[Download standalone PHP script for this example] -> links to examples/object-store/…

General Content Guidelines

These guidelines are generally applicable when writing user-facing documentation for this project. They apply to the Getting Started Guides as well as the Complete User Guides.

• Use commonly-understood terms for services (e.g. Compute) instead of the OpenStack codename (e.g. Nova).
• Try to use well-understood projects when writing guides for a service (e.g. a blog project that could use Object Store to store its images) . This will reduce cognitive load on readers.
• Please make sure to document method parameters, especially if they are optional and therefore left out in the example code. Even better might be to link method calls in example code to phpdoc-generated documentation (but, at this point, I'm not entirely sure how to do this without being too distracting to the reader; some experimentation needed).