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

[Richard Duivenvoorde]

I'm trying out some things here, and added the 'contents' directive
(temporarily) to all rst files in the 'working_with_vector' directory:

.. contents::
   :local:

This will be shown both in Github as a page content (you can set the
level of index):

https://github.com/qgis/QGIS-Documentation/blob/master/source/docs/user_manual/working_with_vector/vector_properties.rst

And in our sphinx build:

http://test.qgis.org/testing/en/docs/user_manual/working_with_vector/vector_properties.html

NOTE url above is at test.qgis.org, docs.qgis.org is via servers of
cloudflare, but test.qgis.org is straight to our server.
This means that after a fresh build (which I just started) you can see
the result immediatly. So both test and docs are actually pointing to
the same host/dir, but the test one is NOT cached !!

Anyway, what about keeping the rst files long and adding this contents
directive to those pages?

Regards,

Richard Duivenvoorde


On 28-01-16 13:45, DelazJ wrote:
> Hi,
> Agreed, the Table of Contents needs to be improved, to help the reader
> know where he is. This was the behaviour until 2.2 and this is how it
> behaves in qgis.org <http://qgis.org> website.
> 
> 2016-01-27 13:37 GMT+01:00 Frank Sokolic <sokolic at worldonline.co.za
> <mailto:sokolic at worldonline.co.za>>:
> 
>     Hi all,
> 
>     My preference is for shorter pages but with with improved navigation
>     so that users know where they are in the documentation.
> 
>     I find the navigation in the user guide frustrating at times. For
>     example, have a look at "Working with Vector Data":
>     http://docs.qgis.org/2.8/en/docs/user_manual/working_with_vector/index.html
> 
>     At the top of this page is a list hyperlinks showing all the topics
>     in this section. However, if you click on one of the hyperlinks then
>     a new page is opened but the list of topics disappears and the user
>     doesn't know where they are anymore.
> 
>     If long pages are split into a series of short pages then I think
>     that the list of topics and sub-topics should appear in the Table of
>     Contents on the left as a nested list and the current topic/page
>     should be highlighted. In this way it would be easier for users to
>     navigate the manual.
> 
>     Regards, Frank.
> 
> 
> 
>     On 27/01/2016 14:06, DelazJ wrote:
> 
>         Hi documenters,
> 
>         There's currently a discussion
>         (https://github.com/qgis/QGIS-Documentation/pull/760) whether long
>         one-page chapters should be divided into shorter pages (files)
>         or not.
>         Richard is less enthusiastic with split because he's afraid that
>         increasig the number of files (thus pages) means more resources,
>         more
>         clicks and may increase the build (and transifex-push) time.
>         At the other hand, short and single-feature pages easier navigation,
>         reading, updating, ensures no repetition and, given that QGIS
>         features
>         are increasing, we risk to end up with very long and less usable
>         pages
>         (scrolling is difficult, no way to directly reach section of
>         interest...).
> 
>         An example can be viewed here:
>         http://docs.qgis.org/2.8/en/docs/user_manual/print_composer/print_composer.html
>         vs
>         http://docs.qgis.org/testing/en/docs/user_manual/print_composer/index.html
> 
>         We'd like to hear your voices about splitting chapters in
>         general and
>         especially in PR 760 on splitting Editing vector layer chapter
>         (http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/editing_geometry_attributes.html).
> 
>         I also made a Pull Request on splitting layer vector properties (see
>         https://github.com/qgis/QGIS-Documentation/pull/776). now broken but
>         comments are welcome.
> 
>         PS: note that in PR760, there's also a discussion about how to
>         better
>         structure the "Working with vector layer" chapter. It's worth your
>         comments, too.
> 
>         Regards,
>         Harrissou
> 
> 
>         _______________________________________________
>         Qgis-community-team mailing list for organizing community
>         resources such as documentation, translation etc..
>         Qgis-community-team at lists.osgeo.org
>         <mailto:Qgis-community-team at lists.osgeo.org>
>         http://lists.osgeo.org/mailman/listinfo/qgis-community-team
> 
> 
>     _______________________________________________
>     Qgis-community-team mailing list for organizing community resources
>     such as documentation, translation etc..
>     Qgis-community-team at lists.osgeo.org
>     <mailto:Qgis-community-team at lists.osgeo.org>
>     http://lists.osgeo.org/mailman/listinfo/qgis-community-team
> 
> 
> 
> 
> _______________________________________________
> 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
>