Open Stack

On 07/14/2015 03:51 PM, Matt Kassawara wrote:
> 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?).

But it covers many different topics, some not even really related 
(besides it's all Identity)

> 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.


So, what are you saying to my reviews?

Those files should include the content directly instead of using the 
include instruction?

Or the files are fine as is?

Thanks for looking into this,
Andreas

> On Sun, Jul 12, 2015 at 3:34 AM, Andreas Jaeger <aj at suse.com
> <mailto: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 <http://suse.com>,opensuse.org
>     <http://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
>     <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
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>


-- 
  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