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

[Michael Kirk]

Thank you for putting together this proposal Richard. 

I think you have proposed some good ways to lower the bar on documentation contributions. 

To *really* see what your changes look like you need too build the docs. Doing this via the docker scripts isn’t too bad, but being familiar with docker is definitely too high a bar for encouraging casual doc contributions.

So, in lieu of that, taking maximal advantage of GitHub’s rendering of .rst is a great option.

By preferring more vanilla rst directives over our custom rst directives we can have our docs looking better in Github, and give contributors a better idea of what their built docs will look like.

And obviously getting images to render is a big win.

I’m not familiar with how we translate docs. Will this affect our translations in any way?

M


Thu Dec 24 13:55:58 UTC 2015 Richard Duivenvoorde richard at duif.net :

> 
> 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)..

> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20151225/999334c5/attachment.html>