Open Stack

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!
Anne


> Thanks a lot!
>
> Kind regards,
>
> Tanja Roth, Documentation
> SUSE Linux GmbH
>
> GF: Felix Imendörffer, Jane Smithard, Jennifer Guild, Dilip Upmanyu,
> Graham Norton HRB 21284 (AG Nürnberg)
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>

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

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