Open Stack

On includes...

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.

On structure...

I prefer the single large HTML file with anchors for the following reasons:

1) Easier navigation due to shallower structure (lack of pages mostly
consisting of links to other sections).
2) Easier string searches with all content for a topic on a single page
(EPPO?).
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.

On Sun, Jul 12, 2015 at 3:34 AM, Andreas Jaeger <aj at suse.com> wrote:

> Btw. I think we misused the include when converting. We now have files
> that are very large HTML files but were separate before.
>
> Have a look at:
> https://review.openstack.org/#/c/200869/
> and compare the new content:
>
> 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
>
> the old docbook one:
>
> http://docs.openstack.org/admin-guide-cloud/content/ch_admin-openstack-orchestration.html
>
> and the current converted one where everything is on a single page:
> http://docs.openstack.org/draft/admin-guide-cloud-rst/orchestration.html
>
>
> Similar check the Identity chapter in current RST where everything is a
> single page:
>
> http://docs.openstack.org/draft/admin-guide-cloud-rst/identity_management.html#use-trusts
>
> and compare with the DocBook
> http://docs.openstack.org/admin-guide-cloud/content/ch-identity-mgmt-config.html
>
> And then check my proposed change:
> https://review.openstack.org/200874
>
> and look at the html:
>
> 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
>
>
> Andreas
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>    GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,
>        HRB 21284 (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/20150714/83fd7f47/attachment.html>