Open Stack

On Tue, Jan 14, 2014 at 3:26 PM, Andreas Jaeger <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,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
> 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/1e2d880e/attachment.html>