Open Stack

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

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

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)