[Qgis-community-team] Doc writing: simpler writing and styling

[Richard Duivenvoorde]

Hi PSC/Community,

Because I think we should attract more people to write documentation for
QGIS, I thought we should make it easier to fix/write docs.

My idea: let's keep our rst framework, but do the editing/viewing in
Github..

First: look at the following two examples:

[0]
https://github.com/FOSS4GAcademy/GST101FOSS4GLabs/blob/master/Module%204%20Lab/QGIS%202.8/Module%204%20Lab.md

and

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

As you can see the first one is immediately readable (and more editable)
in Github.
We have (I think from our Latex roots) a lot of extra styling
directives/stuff in our docs. It looks like this now:

[3]
http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/vector_properties.html#the-vector-properties-dialog

I propose and tested the following:

- move images from resources into an images directory in the source
folder, see
[4]
https://github.com/qgis/QGIS-Documentation/tree/master_github_e/source/docs/user_manual/working_with_vector

- remove all the :guilabel: :menuselection: and other directives to make
it easier to edit/view in Github

- get rid of all/most of the image/icon shortcuts (needed for inline
images) from source.conf and put them in the source file where they are used

- remove substitutions like |qg| (for QGIS) and |nix| (for linux icon).
It clutters the source as seen on Github.

I branched docs and changed one file, look at the Github preview now:

[6]
https://github.com/qgis/QGIS-Documentation/blob/master_github_e/source/docs/user_manual/working_with_vector/vector_properties.rst

As you can see it is the same file as the rst above [1], but here you do
not see all the :xxxx: directives, you see the images etc. Hopefully
much easier to add or fix a paragraph here.

I did not yet move all the image substitutions but if you put those IN
the source file and point to the local image dir, you see them also in
Github.

An example local build here next to a classic build:
http://i.imgur.com/SjSC94N.png

I also build the pdf. Because style directives like :guilabel: also are
followed by text in `back quotes` it still gets a special styling:
italic in pdf and 'cite' in html
So the stuff that is now bleu in html can for example be made italic or
bold easily.

So should I make a QEP for this.
Should I just GO?
Do people REALLY miss the extra styling?

Otto what do you think?

The whole plan/vision is that by looking cleaner/better in Github, it is
easier for people to edit/fix stuff in docs: so we have better
Documentation!

Parts of it can be automated, as nobody has recent translated images
there is not so much work in resources directory.
I think we should start with the User Manual first.
Then Python Cookbook, then Training Manual..

Regards,

Richard Duivenvoorde

PS, part 2 of all this is to fix some styling in the sphinx templates:
remove bootstrap so hopefully it is easier to use docs in Webkit-widgets
again (an early attempt in processing failed, I think because bootstrap
uses to much javascript magic to make content responsive)..