Open Stack

Hi Anne, hi Andreas,

thanks for the replies and guidelines, incl. the pointers to further
sources of information. :)

On 2015-02-27  8:24 Anne Gentle <annegentle at justwriteclick.com> wrote:
>On Tue, Feb 24, 2015 at 11:41 AM, Tanja Roth <taroth at suse.com> wrote:
>
>> Hi,
>>
>> as I did not find answers to some of my questions (mostly conceptual
>> ones and questions regarding best practices) at
>> https://wiki.openstack.org/wiki/Documentation/HowTo, I'm posting them
>> to this list, hoping that you can help me to sort things out: :)
>>
>>
>Great questions, I'll try my best.
>
>
>> - Is http://docs.openstack.org/glossary/content/glossary.html a
>> common glossary for *all* OpenStack documentation? Or are there also
>>   book-specific glossaries? I think maintaining a global glossary is
>>   probably the easiest way to cope with terminology. However,
>>   when using a global glossary, we somehow need to make clear which
>>   context a certain term belongs to (especially, if it has different
>>   meanings in different contexts). How to do so? Just describe the
>>   context withing the respective entry for the term?
>>
>
>Yes, global glossary is the way to go. However I don't know yet how to
>do that in the RST world, but we need to keep this as it's a huge time
>saver and consistency gain. I would describe context within the entry
>for the term.
>
>
>>
>> - Is it possible to link to a certain term in the glossary from the
>>   OpenStack manuals? In DocBook, this is possible - not sure of RST,
>>   though. Do you make use of pointing to a certain term in the
>>   glossary at all? Or is this something you rather avoid?
>>
>
>Right, not sure in RST. Bug logged [1] Our mockup [2] definitely has
>CSS/JS that lets us highlight glossary entries, make popovers, and
>turn them off (green i symbol for Toggle Definitions on the mockup).
>
>
>>
>> - Related to the question above: Often the pure definition of a term
>>   (like you would have it in a glossary) is not enough to introduce a
>>   concept (especially, if it is a complex one).
>>
>
>Sure, concepts are often addressed in the overviews.
>
>
>>
>>   How do you deal with the explanation of concepts that are needed in
>>   multiple manuals (or at multiple places within one manual)? For
>>   example, in the User Guides, the same concepts (e.g. quotas) are
>>   covered in two chapters, the command line chapter and the Web UI
>>   chapter. Do you explain the same concept multiple times (in each
>>   chapter or book where you need the information)? But this is
>>   error-prone in case you need to adapt the information at some point
>>   in time... Or do you explain it in only one place/file and then
>> link to it whenever you need the same information? But it can also be
>>   annoying for readers if they have to follow a heap of links...
>>
>>
>In an every page is page one scenario which we are trying to achieve
>with the revision, you explain in one place, but you may not even link
>to it because of the annoyance factor. You trust that the seeker finds
>the conceptual page when she needs conceptual information. I know it's
>a bit "trust-based" but it's a choice we're making.
>
>
>> - Who writes/maintains the information in the Horizon tooltips and
>> the help texts for command line options? Is this done by developers
>> only or are there doc people involved, too? I'm asking because if
>>   tooltips/command line help is consistent and in good shape, some of
>>   the doc effort in the manuals could perhaps be reduced. IMHO, using
>>   tables with referential information within procedures (for
>> example, to explain individual quota parameters/options) IMHO
>> impairs reading fluency. If the same stuff is already explained in
>> the tooltips or command line help (in a way that is understandable
>> to the respective target group), why not just point to those sources
>> for more details about the available options?
>>
>
>The developers, who I'm sure would welcome doc input and seek it out.
>Honestly they do a decent job and you could delete docs that you think
>are redundant efforts that aren't worth the maintenance, I'd back that.
>
>
>>
>> - My last question is rather specific to the Admin User Guide and End
>>   User Guide (which are partially very similar in content): how to
>>   decide *where* to cover a certain topic? Judging on the basis of
>> the software only (=is the option accessible for admin users or end
>>   users?) is often not a good solution as some options are available
>>   to both (and, what is worse, in Horizon often with slight
>>   differences, depending on whether you access a certain option from
>>   the project tab or the admin tab...). Which criteria do you use to
>>   decide about this?
>>
>>
>Use Admin-only conditionals as lightly as possible and only when the
>entire topic is admin-only. If you see a case where a para-level
>inclusion/exclusion makes sense, bring it here for evaluation because I
>really want to avoid those if we can in our brave new world, it's just
>a bit much for the rest of the contributor base to wrap their heads
>around. Concrete examples will help evaluate the criteria we need.
>
>If you want to read more about "every page is page one" philosophy and
>approach, see
>http://idratherbewriting.com/2012/12/04/what-does-every-page-is-page-one-and-include-it-all-filter-it-afterward-mean/
>
>What we don't have now is filtering based on tags, something that is
>also in the mockup and has a bug logged to implement. [3]
>
>Your questions show your deep knowledge of tech comm and care for our
>users, thank you so much!

>1. https://bugs.launchpad.net/openstack-manuals/+bug/1421813
>2. http://openstack-homepage.bitballoon.com/docs/book
>3. https://bugs.launchpad.net/openstack-manuals/+bug/1421822
>