Open Stack

As for ops guide, Dave Cramer was looking at integrating the glossary. I can't remember what happened.

As for the work involved, it's not a big effort - not equal to work for and index.  But I agree, the more conceptual books would benefit from inclusion of a glossary.

Sent from my iPhone

On Jan 15, 2014, at 9:20 AM, "Anne Gentle" <anne at openstack.org<mailto:anne at openstack.org>> wrote:




On Tue, Jan 14, 2014 at 3:26 PM, Andreas Jaeger <aj at suse.com<mailto:aj at suse.com>> wrote:
I had some discussion with Diane and David about glossary usage and
summarize my understanding and a proposal here.

We have a great glossary (see
http://docs.openstack.org/glossary/content/glossary.html)  and only the
Security Guide uses it to produce some entries:
http://docs.openstack.org/security-guide/content/go01.html


I do like our glossary and how the Security Guide uses it. It's a good standard. I'll have to see if we can do it for the Ops Guide as well. Diane do you remember any limitations there? I'll also have to be sure it fits with O'Reilly's toolchain.

We use in some places firstterm which is related to the glossary but
does not use it. I propose that we should not use firstterm at all and
use glossterm and include a glossary.


I would be happy to drop a firstterm requirement to push more on getting glossterm marked up. I noticed we don't have glossary markup described in https://wiki.openstack.org/wiki/Documentation/Conventions. I'll take a stab at that using the guidelines below.



I'd also like to investigate a nice Rackspace maven plug-in that allows
to use HTML popups for Glossary definitions.

We can add the glossary to each book we build - either the complete
glossary or just the entries that use "glossterm" in the guide.

My proposal is to make better use of the great glossary we have and thus:
* Deprecate firstterm usage, ask for glossterm

Sounds fine.

* Add glossterm to some terms

This is as much work as maintaining an index so I'm not sure it is worthwhile to focus on that markup rather than writing content.

* Add the glossary to our manuals

I'm not sure that all manuals need a glossary. How about Ops Guide, Install Guide, Sec Guide, and End User Guide only for starters?

The Config ref is too long already, as is the Cloud Admin Guide.


* Display as glossary only the entries that are in the documented

Yes, that's what the markup gives you.

* Evaluate the Rackspace glossary plug-in


Is that for pop-ups in HTML? I'm not a big fan of those but can be swayed.

I propose to start with the Install Guide and then add further guides.

What do you think?

Let me know if you have any thoughts on the above selectiveness...
Thanks!
Anne


Andreas
--
 Andreas Jaeger aj@{suse.com<http://suse.com>,opensuse.org<http://opensuse.org>} Twitter/Identica: jaegerandi
  SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (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<mailto:Openstack-docs at lists.openstack.org>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

_______________________________________________
Openstack-docs mailing list
Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140115/37b721ba/attachment.html>