[Qgis-community-team] Proposal to divide some pages in QGIS documentation

[Yves Jacolin]

Hello,

A big +1 for this. This is something we need to do some time. I remember did 
it for the vector chapter last year.

I started to read and comment your PR. I need to build it before give more 
comment but the PR seems ok for me except one small thing.

Rst engine will always start with a H1 header with the first symbol line found 
in the rst file.

So each time you use ------------------ for instance, it will become a H1 
header [1]. Same for [2] with  ==== line.

There is two small issues with this:
1. it is less readable for the same level of header, if sometime you use 
"----" and another time "==="
2. if later you need to add another (sub)-sectionin [1], you should find 
another symbol, so it will be probably one of ***, ====, +++ and they will 
look a greater level (only to me?).

We should keep rst file human readable.

I will build your PR tomorrow if no one merge your PR before :)

Y.
[1] composer_items/composer_scale_bar.rst
[2] print_composer/first_steps.rst with

Le samedi 6 juin 2015, 01:22:26 DelazJ a écrit :
> Hi Folks,
> 
> While reading QGIS documentation, there are some pages that leave me
> puzzled. You may have a look at Print Composer [1], vector properties
> dialog [2] pages.
> IMHO, these pages are too long. For the reader, scrolling can become
> tedious while looking for a precise information. Sure, the subject is wide
> and there is a lot of informations at these pages but I think that, because
> subject is wide, it can be splited into several pages, shorter, more
> precise and readable. As there are Previous/Next buttons, skipping sections
> while reading can easily be done.
> From writer side, I think that having short (and specialized) page helps us
> to quickly identify where there may be a lack of documentation, easily
> update or improve them...
> 
> So, few days ago, I made a pull request [3] that splits Print Composer
> chapter into many pages, reorganizing sections and sequences.
> 
> If you agree with the spliting principle of these chapters, can some
> documentation writers review it, amend it and let me know if it is ok? It's
> the first time I use rst files so it'd be nice if someone can review my PR
> before I begin spliting vector properties chapter.
> 
> Regards,
> Harrissou
> 
> [1]
> http://docs.qgis.org/2.8/fr/docs/user_manual/print_composer/print_composer.h
> tml [2]
> http://docs.qgis.org/2.8/fr/docs/user_manual/working_with_vector/vector_prop
> erties.html [3] https://github.com/qgis/QGIS-Documentation/pull/544/

-- 
Yves Jacolin