Open Stack

Hi Jakub,
Thoughts below, thanks for sending.


On Tue, May 21, 2013 at 1:52 PM, Jakub Ruzicka <jruzicka at redhat.com> wrote:

> 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?
>
> Sure. More info is good as long as it is accurate (so maintained, that's
the tough part as you allude to).

>
> 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?
>
>
I made an attempt a few releases ago to get nova man pages done in RST. See
https://github.com/openstack/nova/tree/master/doc/source/man. Swift did the
same at https://github.com/openstack/swift/tree/master/doc/manpages. You
could use those to see how rst could work for the clients. However I don't
believe these are accurate since they're not well-maintained. So the format
doesn't necessarily help with maintenance.



>
> 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?
>
>
>
You could log a blueprint for openstack-manuals at
http://blueprints.launchpad.net/openstack-manuals since it's a common doc
consistency task. Not sure the doc team has resources to spare this release
as we have some blueprints that came up prior to the Summit, but I'm happy
to facilitate as needed.
Thanks,
Anne


>
> Thanks in advance for your valuable input!
>
> Jakub Ruzicka
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20130521/8db4dfd1/attachment.html>