<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Tue, Jan 14, 2014 at 3:26 PM, Andreas Jaeger <span dir="ltr"><<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">I had some discussion with Diane and David about glossary usage and<br>
summarize my understanding and a proposal here.<br>
<br>
We have a great glossary (see<br>
<a href="http://docs.openstack.org/glossary/content/glossary.html" target="_blank">http://docs.openstack.org/glossary/content/glossary.html</a>) and only the<br>
Security Guide uses it to produce some entries:<br>
<a href="http://docs.openstack.org/security-guide/content/go01.html" target="_blank">http://docs.openstack.org/security-guide/content/go01.html</a><br>
<br></blockquote><div><br></div><div>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.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
We use in some places firstterm which is related to the glossary but<br>
does not use it. I propose that we should not use firstterm at all and<br>
use glossterm and include a glossary.<br>
<br></blockquote><div><br></div><div>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 <a href="https://wiki.openstack.org/wiki/Documentation/Conventions">https://wiki.openstack.org/wiki/Documentation/Conventions</a>. I'll take a stab at that using the guidelines below.</div>
<div><br></div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
I'd also like to investigate a nice Rackspace maven plug-in that allows<br>
to use HTML popups for Glossary definitions.<br>
<br>
We can add the glossary to each book we build - either the complete<br>
glossary or just the entries that use "glossterm" in the guide.<br>
<br>
My proposal is to make better use of the great glossary we have and thus:<br>
* Deprecate firstterm usage, ask for glossterm<br></blockquote><div><br></div><div>Sounds fine.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
* Add glossterm to some terms<br></blockquote><div><br></div><div>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.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
* Add the glossary to our manuals<br></blockquote><div><br></div><div>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?</div><div><br>
</div><div>The Config ref is too long already, as is the Cloud Admin Guide. </div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
* Display as glossary only the entries that are in the documented<br></blockquote><div><br></div><div>Yes, that's what the markup gives you.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
* Evaluate the Rackspace glossary plug-in<br>
<br></blockquote><div><br></div><div>Is that for pop-ups in HTML? I'm not a big fan of those but can be swayed.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
I propose to start with the Install Guide and then add further guides.<br>
<br>
What do you think?<br></blockquote><div><br></div><div>Let me know if you have any thoughts on the above selectiveness...</div><div>Thanks!</div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<span class=""><font color="#888888"><br>
Andreas<br>
--<br>
Andreas Jaeger aj@{<a href="http://suse.com" target="_blank">suse.com</a>,<a href="http://opensuse.org" target="_blank">opensuse.org</a>} Twitter/Identica: jaegerandi<br>
SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany<br>
GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)<br>
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126<br>
<br>
_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
</font></span></blockquote></div><br></div></div>