Open Stack

Hello,

I plan to provide consistent man pages for all OpenStack clients and I'd
love to see your opinion about few important details:


GENERATED VS MANUAL
===================

Although man pages can be generated the same way as help, a copy of help
output doesn't bring any real value.

Man page should provide something extra like:
 * verbose descriptions of more complicated commands/options
 * howto use the tool to solve common tasks
 * examples of usage
 * where to find more information

Do you see any value in including the command list in man page without
providing more detailed information than `$CLIENT help` does?


FORMAT
======

man format is ugly and hard to maintain, man page should be stored in
something saner like reStructuredText or AsciiDoc.

Which format do you recommend?


CONTENTS
========

I'd like to include few useful examples of most common use cases for sure.

Beyond that, there are basically 3 options:

1) Provide only basic information with bold
"""
Run `$CLIENT help` to get available commands and their descriptions.

Run `$CLIENT help <command>` to get information about <command>.
"""

2) Provide detailed information about selected commands/features/tasks only.

3) Provide detailed information about all commands. As I don't have so
much time on my hands, I'd start with `$CLIENT help` (pretty much what
help2man outputs) and extend it over time with detailed information.
I don't like this very much because:
 * Will someone actually extend it?
 * This would require maintenance and could easily go out of sync.

What should be in the man page?


BLUEPRINT
=========

What is the best way to create a blueprint concerning multiple
components (all the clients) in LP?



Thanks in advance for your valuable input!

Jakub Ruzicka