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

[Otto Dassau]

Hi,

I agree, it probably looks confusing, if we
remove :guilabel:, :menuselection: etc from the rst files. So I would vote
for keeping them.

Regards,
Otto

Am Wed, 27 Jan 2016 11:31:07 +0100
schrieb DelazJ <delazj at gmail.com>:

> Hi,
> with the removal of :guilabel: and :menuselection: which clearly will
> easier doc writing, i'm afraid that user might be confused while reading
> doc. Indeed, the GUI labels are now rendered as simple text, same font.
> When reading, you may now not know which part of the text is GUI option and
> what is description, explanation. Since the GUI labels are still put
> between _`_ characters, shouldn't we give it a special font, font size,
> style...?
> see
> http://docs.qgis.org/2.8/en/docs/user_manual/working_with_vector/vector_properties.html
> vs
> http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/vector_properties.html
> 
> Regards
> 
> 2016-01-20 11:32 GMT+01:00 DelazJ <delazj at gmail.com>:
> 
> > Hi,
> >
> > +1 for using GitHub issue report. Note that there's a pending PR (
> > https://github.com/qgis/QGIS-Website/pull/308) that supports this idea.
> >
> > 2016-01-18 13:53 GMT+01:00 Alexandre Neto <senhor.neto at gmail.com>:
> >
> >>
> >>
> >> Richard Duivenvoorde <richard at duif.net> escreveu no dia domingo,
> >> 17/01/2016 às 19:04:
> >>
> >>> - is is still usefull to have the 'Operating System' icons around (that
> >>> is the little Mac, Linux and Windows icons) for screenies OR when the
> >>> instructions differ...
> >>>
> >>
> >> Screenshots are all (or almost) in linux anyway, so for that they are
> >> not needed at all.
> >>
> >>
> >>> - we/I have still test what happens with the translations of sentences
> >>> which we remove directives and substitutions from (I hope the old
> >>> translations will be available in the glossary....)
> >>>
> >>>
> >> I think this process will, for sure, cause many untranslated strings to
> >> translate again... For this, I think a warning in QGIS-tr list would be
> >> advisable, because there are some language teams that made a huge
> >> effort to reach this percentage of translation. But this will also make
> >> translation easier with the removing of all
> >> the :guilabel: :menuselection.
> >>
> >>
> >>> If nobody objects, I'll start (in one commit) to do this page:
> >>>
> >>>
> >>> https://github.com/qgis/QGIS-Documentation/blob/master_github_e/source/docs/user_manual/working_with_vector/vector_properties.rst
> >>>
> >>>
> >> +1
> >>
> >> Regarding managing the Documentation update I would also prefer using
> >> github issues to manage the documentation update effort.
> >>
> >> Reviewing all "automatic new features", close them if it does not imply
> >> any changes to the documentation, or label it if it does, would be my
> >> first step.
> >>
> >> If possible I would advice using labels to identify what needs to be
> >> updated (text, screenshots) and where (Users manual, python cookbok,...)
> >> for each issue.
> >>
> >> Thanks
> >>
> >> Alexandre Neto
> >> --
> >> Alexandre Neto