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

[Otto Dassau]

Hi Alexandre,

thanks a lot for your help! Since feature freeze already started, you could
start updating existing figures, if necessary, I guess. So you have about 6
weeks from now...

Regards,
Otto

Am Sat, 16 Jan 2016 23:18:09 +0000
schrieb Alexandre Neto <senhor.neto at gmail.com>:

> I will be available for updating the figures for 2.14. But I doubt I can do
> it in a week.
> 
> A 19h54 Sáb, 16 de Jan de 2016, Otto Dassau <otto at qgis.org> escreveu:
> 
> > 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
> > _______________________________________________
> > 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