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

[Frank Sokolic]

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.

Regards, Frank.

On 28/01/2016 16:43, Richard Duivenvoorde wrote:
>
> 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
>>
>
> _______________________________________________
> 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
>