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

Sat Jan 16 15:18:09 PST 2016

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

-- 
Alexandre Neto
---------------------
@AlexNetoGeo
http://sigsemgrilhetaswordpress.com
http://gisunchained.wordpress.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20160116/264c7f64/attachment.html>