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

[Diethard Jansen]

Hi Richard,

- I like the idea of having images in the source directory of screenshots
of windows/panels and being able to explain the functionality that is
included in the image. You still see options to include a translated
screenshot when you include these from images?

- I do not like the idea if this means we are going to have many duplicated
images of icons in many images directories. In that case I am in favour to
keep them defined in one single place and to include these as a
substitution. The big advantage is when the image of the icon is replaced,
you only have to replace it in one place. I am in favour of using
subsitutions for icons only!

- It may be a good idea to move the substitutions out of conf.py to
icon_substitutions.py next to conf.py and use "import icon_substitutions"
statement in conf.py. We should remove all unused icon substitions.

- Whatever is decided, please keep an eye on impact for already translated
work. Instead of a big bang where a lot of translation work has to be
restarted, I would rather opt for a gentle replacement of one technique
with the other. It can be very discouraging to translators to continue when
too much translation work has gone in one courageous action. For example,
replacing all |qg| is very easy, but the impact on translated work is
pretty big. I would replace this substition only during a rewrite of text.

Regards,
Diethard.



2015-12-24 14:55 GMT+01:00 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)..
>
>
> _______________________________________________
> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20160108/8f85b3e1/attachment.html>