Open Stack

Hi Tanja,

just a few brief comments - if those are too short, ping me tomorrow and
I can give you full details.

On 02/24/2015 06:41 PM, Tanja Roth 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: :)
> 
> - Is http://docs.openstack.org/glossary/content/glossary.html a common
>   glossary for *all* OpenStack documentation? Or are there also

Yes.

>   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? 
> 
> - 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?  

Search for glossterm usage - some guides do this better than others...

> - 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). 
> 
>   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...
> 
> - 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

Developers mainly. Some of us send patches if we notice real problems
but in general documentation team is not involved.

>   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? 
> 
> - 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?
> 
> Thanks a lot!  

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