Open Stack

On Mon, Apr 6, 2015 at 10:28 AM, Karen Bradshaw <kbhawkey at gmail.com> wrote:

> Hi.  I do not have an opinion about including the tables and figures.
> Just checking on what should be included or not.
>

So far we are reviewing with a convention that we don't have captions on
figures or labels on tables. (Ha! That rhymes.) Let's stick with that
convention.


> The links provide another navigation point into the documentation.
> For information that is used frequently, say a common installation routine
> or
> API commands, a link may be useful.
>

Agreed, but I don't know how to make those with Sphinx right now, so at
this point in the migration we won't plan on doing those.


> I can try and do the initial conversion of app_support.xml to
> user-guides/source/common/app_support.rst?  Where would this file be
> included, under indices and tables in index.rst and index-admin.rst?
>

Yep, you got it!

Anne


> -Karen
>
> On Mon, Apr 6, 2015 at 10:54 AM, Anne Gentle <
> annegentle at justwriteclick.com> wrote:
>
>>
>>
>> On Mon, Apr 6, 2015 at 9:48 AM, Andreas Jaeger <aj at suse.com> wrote:
>>
>>> On 04/06/2015 03:38 PM, Karen Bradshaw wrote:
>>>
>>>> Hi. I am reviewing the new content generated for the admin user guide.
>>>>
>>>
>>> thanks!
>>>
>>>  Is there a plan to add an appendix for community support information?
>>>>
>>>
>>> IMHO it would be great to have it. Do you want to convert it?
>>
>>
>> Please do add it. If you can't convert it, just let me know and I'll do
>> it.
>>
>>
>>>
>>>
>>>  How about adding labels for the tables and figures?
>>>>
>>>
>>> If we do this, let's write it down on our markup conventions page as
>>> well. I'm not feeling strongly either right now,
>>>
>>
>>
>> Currently our convention for RST markup is to only use the image
>> directive. We'd have to start using the figure directive in order to get a
>> caption for each figure.
>>
>> https://wiki.openstack.org/wiki/Documentation/Markup_conventions#Image
>> is where the convention is documented.
>>
>> For tables, I'm not aware of a way to ensure a caption is used, other
>> than to put it in our conventions as a paragraph before the table.
>>
>> With the migration goal of simplifying and welcoming more contributors,
>> it seems a little heavy-handed to require captions for tables and figures.
>> So I want to hear why we would require them other than "we've done it that
>> way before." Any thoughts? I can't justify the overhead when we aren't
>> doing collections of them in the new world. Any other thoughts?
>>
>> Thanks,
>> Anne
>>
>>
>>>
>>> Andreas
>>> --
>>>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>>>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>>>    GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu,
>>>        Graham Norton, HRB 21284 (AG Nürnberg)
>>>     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>>>
>>>
>>> _______________________________________________
>>> OpenStack-docs mailing list
>>> OpenStack-docs at lists.openstack.org
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>>
>>
>>
>>
>> --
>> Anne Gentle
>> annegentle at justwriteclick.com
>>
>
>


-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150406/7595b4b7/attachment.html>