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

Sun Jan 17 06:36:10 PST 2016

I will start soon.

I would like to ask people to add the screenshot label to issues that need
figures update.

Thanks.

Alexandre

A 9h17 Dom, 17 de Jan de 2016, Otto Dassau <otto at qgis.org> escreveu:

> 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
> _______________________________________________
> 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/20160117/a02e8313/attachment.html>