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: docs and samples. The docs directory will contain the actual user-facing documentation while the samples directory will contain standalone PHP scripts for individual tasks (such as creating a container). The documentation in the docs directory will reference the sample scripts in the samples directory, letting the user download standalone, working versions of PHP code for examples shown in the documentation.

The docs 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 samples directory will also contain subdirectories. These subdirectories will mirror those under docs/user-guides.

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

 samples/
   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 samples/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.

Try to use a consistent commonly-known theme (e.g. a contrived blog project) throughout each service's Complete User Guide. 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 sample code. Even better might be to link method calls in sample 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).

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 samples/object-store/create-container.php

Common use case #2

 code snippet 3

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