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

[Yves Jacolin]

Harrissou,

I agree with you but your 3 propositions are not really proposition because as 
you said 1. is not appropriate (I agree completly with you), 2. needs somt 
work and I think it is not possible to mix branch into transifex or will add 
more complexity and 3. well, ...   :)

For me, if I need a choice between this 3 propositions, I am in favor of #3. 
We can have a "third" repository for a "static" documentation (means not link 
to a QGIS release), WebSite and QGIS doc are the 2 first in my mind.

Y.
Le samedi 22 avril 2017, 19:27:42 CEST DelazJ a écrit :
>  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.h
> tml> 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.h
> tml>
> 
> 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