[Qgis-community-team] Split or not some long chapters into shorter pages?

[DelazJ]

Hi,
I up this thread given that there were (?) pending PRs and unless i miss
something, no decision has been taken to close this discussion (and I
didn't "hear" so many voices).

I must confess that at the beginning I wasn't fan of  the "contents at the
top of the page" (as currently proposed in e.g.
http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/style_library.html).
But while navigating through these pages, it offers the reader an overview
of the content of the page, a quick way to access the desired link. From a
documenter point of view, it helps to understand how the chapter is
structured, identify where a new section can be added or moved to. It's
definitely an useful enhancement we should add to all compatible pages.
Even though it makes some pages noticeably longer (what was the issue
reported here) imho it's worth the length and combining the Home button and
the content-toc does really simplify navigation.

However, we still have issues with navigation, i think.
Richard, about the template of the pages, do you mean that having an
expandable TOC like it's done for the QGIS website (e.g.,
http://qgis.org/fr/site/getinvolved/development/qgisdevelopersguide/codingstandards.html)
or for 2.2 docs (
http://docs.qgis.org/2.2/en/docs/user_manual/working_with_vector/vector_properties.html)
will require a lot of changes and complicates migration? Currently when you
are at
http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/style_library.html,
it's not that easy to identify in the TOC in which chapter you are and more
interesting what are the other sections/topics covered in the same chapter.
I think that covering also this (even only for the first level under the
main chapter) will provide great improvements to readers and writers.

Sorry to come only with my words (in a rough english) and not be able to
come with a technical proposal (I unfortunately have no great skill in this
area).

Regards,
Harrissou

2016-01-29 11:33 GMT+01:00 Richard Duivenvoorde <richard at duif.net>:

> On 29-01-16 10:28, Frank Sokolic wrote:
> > Having the contents at the top of the page is an improvement. Is it
> > possible to have hyperlinks back to the contents next to each section
> > heading in the long rst files? This would make it easier for users to
> > jump back to the contents instead of having to scroll all the way back
> > to the top.
>
> Well, at least for the docs website we could inject some floating div
> somewhere on the bottom. Maybe combined with some links to the same page
> in other versions? This (via javascript injected) html would probably
> not be shown on github.
>
> On the other hand: does not everybody have a 'home' button, which will
> bring you to top == contents?
>
> I hope to keep the template stuff as default as possible to make it easy
> to move to another template in near future.
>
> Regards,
>
> Richard
> _______________________________________________
> Qgis-community-team mailing list for organizing community resources such
> as documentation, translation etc..
> Qgis-community-team at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/qgis-community-team
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20160217/3f26f3b9/attachment.html>