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

[Otto Dassau]

Hi Richard and Diethard,

I have some questions about the best procedure to update the user manual.
Could you please check and tell me, if I am wrong? I would prepare the
following:

a) Go through the "User Manual" issues and add missing issues that need to
   be documented for 2.14. from changelog.
   https://github.com/qgis/QGIS-Documentation/issues?q=is%3Aopen+is%3Aissue+label%3A%22User+Manual%22
b) Create a list which issues should go to which chapter and make a
   proposal which could be done by whom. 
c) Write a short documentation about updating the manual and adding it to
   http://www.qgis.org/en/site/getinvolved/document.html
d) ask manual update team to create a github account, if not already done.
   Allow them to write in the documentation repository. The manual updates
   would take place in master branch.
e) Assign issues to documenters, so they can start working based
   on the latest qgis master (nightly build), now that feature freeze has
   started.

I plan to finish these steps within the next week, so we could start with
the 4 week time period not later then 25th January. If someone can help
with the preparations, it would be great.

And what about the figure updates. Should we also do that before we start,
so it is easier for documenters to write the manual? And would that
be possible anyway within such a short time frame? Although I see the problem
of duplication (only for icons, isn't it?) I would still go with the proposal
from Richard.

@Diethard: According to a "big bang" for the translation. I guess this will
happen anyway, since we plan also to review the manual and I also guess that
there will be many changes...

Regards
Otto

Am Fri, 8 Jan 2016 18:19:02 +0100
schrieb Diethard Jansen <diethard.jansen at gmail.com>:

> 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