<div dir="ltr">I'd like to see more details provided through oslo.config (perhaps an verbose_description kwarg for each option, or something similar?), so that we can render that additional documentation to multiple formats (man pages, openstack manuals, etc) beyond CLI --help.<br>
</div><div class="gmail_extra"><br clear="all"><div><div><br></div>-Dolph</div>
<br><br><div class="gmail_quote">On Tue, May 21, 2013 at 2:00 PM, Anne Gentle <span dir="ltr"><<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr">Hi Jakub, <div>Thoughts below, thanks for sending. </div><div class="gmail_extra"><br><br><div class="gmail_quote"><div class="im">On Tue, May 21, 2013 at 1:52 PM, Jakub Ruzicka <span dir="ltr"><<a href="mailto:jruzicka@redhat.com" target="_blank">jruzicka@redhat.com</a>></span> wrote:<br>


<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">Hello,<br>
<br>
I plan to provide consistent man pages for all OpenStack clients and I'd<br>
love to see your opinion about few important details:<br>
<br>
<br>
GENERATED VS MANUAL<br>
===================<br>
<br>
Although man pages can be generated the same way as help, a copy of help<br>
output doesn't bring any real value.<br>
<br>
Man page should provide something extra like:<br>
 * verbose descriptions of more complicated commands/options<br>
 * howto use the tool to solve common tasks<br>
 * examples of usage<br>
 * where to find more information<br>
<br>
Do you see any value in including the command list in man page without<br>
providing more detailed information than `$CLIENT help` does?<br>
<br></blockquote></div><div>Sure. More info is good as long as it is accurate (so maintained, that's the tough part as you allude to).  </div><div class="im"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">



<br>
FORMAT<br>
======<br>
<br>
man format is ugly and hard to maintain, man page should be stored in<br>
something saner like reStructuredText or AsciiDoc.<br>
<br>
Which format do you recommend?<br>
<br></blockquote><div><br></div></div><div>I made an attempt a few releases ago to get nova man pages done in RST. See <a href="https://github.com/openstack/nova/tree/master/doc/source/man" target="_blank">https://github.com/openstack/nova/tree/master/doc/source/man</a>. Swift did the same at <a href="https://github.com/openstack/swift/tree/master/doc/manpages" target="_blank">https://github.com/openstack/swift/tree/master/doc/manpages</a>. 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.<br>


</div><div class="im"><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
CONTENTS<br>
========<br>
<br>
I'd like to include few useful examples of most common use cases for sure.<br>
<br>
Beyond that, there are basically 3 options:<br>
<br>
1) Provide only basic information with bold<br>
"""<br>
Run `$CLIENT help` to get available commands and their descriptions.<br>
<br>
Run `$CLIENT help <command>` to get information about <command>.<br>
"""<br>
<br>
2) Provide detailed information about selected commands/features/tasks only.<br>
<br>
3) Provide detailed information about all commands. As I don't have so<br>
much time on my hands, I'd start with `$CLIENT help` (pretty much what<br>
help2man outputs) and extend it over time with detailed information.<br>
I don't like this very much because:<br>
 * Will someone actually extend it?<br>
 * This would require maintenance and could easily go out of sync.<br>
<br>
What should be in the man page?<br>
<br>
<br>
BLUEPRINT<br>
=========<br>
<br>
What is the best way to create a blueprint concerning multiple<br>
components (all the clients) in LP?<br>
<br>
<br></blockquote><div><br></div></div><div>You could log a blueprint for openstack-manuals at <a href="http://blueprints.launchpad.net/openstack-manuals" target="_blank">http://blueprints.launchpad.net/openstack-manuals</a> 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.</div>


<div>Thanks,</div><div>Anne</div><div class="im"><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">


<br>
Thanks in advance for your valuable input!<br>
<br>
Jakub Ruzicka<br>
<br>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org" target="_blank">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</blockquote></div></div><br></div></div>
<br>_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br></blockquote></div><br></div>