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

[DelazJ]

Hi all,

Yves, thanks for your recommendations about the headers. I'll do the
changes.
I thought that symbols were what define the "level" of the title meaning
that, chapter should always have header (===), section header (---),
sub-section header ... with no link whether they begin a new page or not.
But if I understand u, the right "level" of a title/subtitle is built from
the index files (and folder) and the order of appearance of headers symbol
in each file.
I suppose that, if I want to generate for example a pdf file with these
files, it's the index file (and folder) that tells the Rst engine how to
build the file according to chapter >section > subsection... Am I right?

About an introductive text at the beginning of the chapter, I thought about
this but I was unable to find a chapter with such presentation so I gave
up. I can pick the first two paragraphs of "first step" section, unless one
is enough...

Regards,
Harrissou

2015-06-07 16:16 GMT+02:00 Yves Jacolin <yjacolin at free.fr>:

> 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/
> DelazJ,
>
> My opinions is that your split is perfect. As you said all in one page
> should
> be too much and the split is great.
>
> One more feedback (with my comments in you Pr): the index page contains
> only a
> toc, do you think we can add a small paragraph to introduce the composer
> chapter? As the one in "First Steps" section for instance?
>
> Otherwise just merge.
>
> Y.
> --
> Yves Jacolin
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20150608/3e42288e/attachment.html>