<div dir="ltr"><div>On includes...</div><div><br></div><div>Using includes within a guide make sense for repeating content. However, I'm not sure how much content meets this qualification outside of a few sections in the networking guide. The ability to reuse command (CLI) output increases consistency, reduces errors, and may also hasten updates when commands decide to change flags and/or output. On the other hand, it makes contributions (particularly for new folks) a bit more interesting. Let's decide if we want to use includes or not (perhaps try them in the networking guide?)... and if so, decide on how to make them work best technically.</div><div><br></div><div>On structure...</div><div><br></div>I prefer the single large HTML file with anchors for the following reasons:<div><br></div><div>1) Easier navigation due to shallower structure (lack of pages mostly consisting of links to other sections).</div><div>2) Easier string searches with all content for a topic on a single page (EPPO?).</div><div>3) Fewer issues with deep linking by search engines and people to specific HTML filenames. Links to missing anchors simply redirect to the top of the page rather than 404.</div></div><div class="gmail_extra"><br><div class="gmail_quote">On Sun, Jul 12, 2015 at 3:34 AM, 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:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Btw. I think we misused the include when converting. We now have files that are very large HTML files but were separate before.<br>
<br>
Have a look at:<br>
<a href="https://review.openstack.org/#/c/200869/" rel="noreferrer" target="_blank">https://review.openstack.org/#/c/200869/</a><br>
and compare the new content:<br>
<a href="http://docs-draft.openstack.org/69/200869/1/check/gate-openstack-manuals-tox-doc-publish-checkbuild/1c963f7//publish-docs/draft/admin-guide-cloud-rst/orchestration.html" rel="noreferrer" target="_blank">http://docs-draft.openstack.org/69/200869/1/check/gate-openstack-manuals-tox-doc-publish-checkbuild/1c963f7//publish-docs/draft/admin-guide-cloud-rst/orchestration.html</a><br>
<br>
the old docbook one:<br>
<a href="http://docs.openstack.org/admin-guide-cloud/content/ch_admin-openstack-orchestration.html" rel="noreferrer" target="_blank">http://docs.openstack.org/admin-guide-cloud/content/ch_admin-openstack-orchestration.html</a><br>
<br>
and the current converted one where everything is on a single page:<br>
<a href="http://docs.openstack.org/draft/admin-guide-cloud-rst/orchestration.html" rel="noreferrer" target="_blank">http://docs.openstack.org/draft/admin-guide-cloud-rst/orchestration.html</a><br>
<br>
<br>
Similar check the Identity chapter in current RST where everything is a single page:<br>
<a href="http://docs.openstack.org/draft/admin-guide-cloud-rst/identity_management.html#use-trusts" rel="noreferrer" target="_blank">http://docs.openstack.org/draft/admin-guide-cloud-rst/identity_management.html#use-trusts</a><br>
<br>
and compare with the DocBook <a href="http://docs.openstack.org/admin-guide-cloud/content/ch-identity-mgmt-config.html" rel="noreferrer" target="_blank">http://docs.openstack.org/admin-guide-cloud/content/ch-identity-mgmt-config.html</a><br>
<br>
And then check my proposed change:<br>
<a href="https://review.openstack.org/200874" rel="noreferrer" target="_blank">https://review.openstack.org/200874</a><br>
<br>
and look at the html:<br>
<a href="http://docs-draft.openstack.org/74/200874/1/check/gate-openstack-manuals-tox-doc-publish-checkbuild/9ee3f7e//publish-docs/draft/admin-guide-cloud-rst/identity_management.html" rel="noreferrer" target="_blank">http://docs-draft.openstack.org/74/200874/1/check/gate-openstack-manuals-tox-doc-publish-checkbuild/9ee3f7e//publish-docs/draft/admin-guide-cloud-rst/identity_management.html</a><div class="HOEnZb"><div class="h5"><br>
<br>
Andreas<br>
-- <br>
Andreas Jaeger aj@{<a href="http://suse.com" rel="noreferrer" target="_blank">suse.com</a>,<a href="http://opensuse.org" rel="noreferrer" target="_blank">opensuse.org</a>} Twitter/Identica: jaegerandi<br>
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany<br>
GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,<br>
HRB 21284 (AG Nürnberg)<br>
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126<br>
<br>
<br>
_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">OpenStack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
</div></div></blockquote></div><br></div>