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

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

[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_guidelines/do_translations.html we'll rather open something like
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

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [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


_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Loading...