[Qgis-community-team] Management of release-independent documents

[DelazJ]

 Hi List,

In the QGIS Documentation repository we maintain and publish different
documents:
A/
   - the User Manual
   - the Training Manual
   - the PyQGIS Cookbook
B/
   - the Documentation Guidelines (how to write the docs)
   - the gentle introduction in GIS (what's GIS)
   - and (coming soon) the Developer Guidelines (rules to contribute to
QGIS Desktop and Server coding)

Each time we release a new doc, we actually publish a new version of all
these documents (in html, and some of them also in pdf) and changes in each
of these documents are pushed to translation (currently 18 languages
published).

While the first three documents are really related to and dependent on QGIS
versions, the latter are not. Hence I think we should stop releasing them
altogether and have different cycles of releases:
- release the manuals when they are ready, as we use to do;
- and release the others when there are new texts, the way we do for QGIS
website: this means that there will be a unique version available for these
documents, hence a unique url and they will be live updated and translated.

*Why?*

- The gentle introduction in GIS is almost the same between 2.0, 2.14 and
testing (except typo and rendering fixes). Should we still publish all the
versions?
- The documentation guidelines can change between versions but have
interest only for the document(s) being written so i'm not sure it's worth
publishing previous versions: there's actually no reason for anyone to
check what were the rules in 2.2 e.g.
- The documentation and developers guidelines will gain to be published and
translated when they are needed ie, during writing/coding cycle and not
after the battle, once the targeted version is released.
- with QGIS 3 and its API break, there are some changes to dev guidelines.
It makes no sense to put them in 2.18 doc branch so, according to the
current process, they'd be merged in master branch, hence available in
testing doc. But the testing documentation will not be released before
summer 2018 (as of QGIS3.2 release) so no translated version until then.
While a doc writer should be able to deal with English version of doc
guidelines, speaking English shouldn't be a prerequisite for coders so,
imho (from a non English native speaker) it's really a pity in this case.


*What'd that mean?*

1- remove all links to previous versions of these three documents from
http://qgis.org/en/docs/index.html . By removing these documents for each
previous release, we will aerate a bit that page and clean it fom unneeded
and repetitive documents. It will also free space in our storage disks.
2- with some magic, point them to a url that won't change  E.g. if someone,
for some reasons (bookmark, web search...) try to open
http://docs.qgis.org/2.2/nl/docs/documentation_guidelin
es/do_translations.html
<http://docs.qgis.org/2.2/en/docs/documentation_guidelines/do_translations.html>
we'll
rather open something like
http://docs.qgis.org/nl/docs/documentation_guidelines/do_translations.html
<http://docs.qgis.org/2.2/en/docs/documentation_guidelines/do_translations.html>

3- reorganize the index page to list those unique docs in a more visible
way.

The only issue I can see is how do we manage the only version related page
in documentation guidelines http://docs.qgis.org/testing/
en/docs/documentation_guidelines/substitutions.html

*What in the backend?*

I can see different options:

1/ Move (back?) those documents to QGIS website repository; It'd be the
easiest way but I'm not sure website repo is very appropriate and coherent
to store doc source files
2/ Keeping them in the Documentation repository, use only the master branch
(the basement and red wire branch of the repo) as source; it means that the
master branch will generate:
  - docs in English only (user manual, cookbook and training manual) at
http://docs.qgis.org/testing/en/docs
  - and translated docs (gentle introduction, developers and documentation
guidelines) using e.g. http://docs.qgis.org/nl/docs/ Changes to these
documents will prioritarily go to master
That said, I have no idea of the amount of work it'd require, especially on
Transifex infrastructure (and I do not have the skills to do it)- nor even
if that's possible.
3/ create a dedicated repo: i think we have enough repos to deal with and
if we can avoid a new one, it'd be nice


I hope that my comments are clear enough.
Looking forward to read yours!

Harrissou
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20170422/659082c9/attachment.html>