On the road to QGIS3

Ideas to structure the next QGIS documentation generation

Relation between QGIS Docs and Desktop

Links to doc sections are added to QGIS Desktop dialog help buttons. Nice!! Now, How do we manage update? How do we manage translation process regarding this change? How do we ensure that links are still valid? The better those considerations are managed, the better using doc to provide help in application experience will be a success for the project. Some concerns below:

A default link is provided, using the qgis_version (currently 2.99 returns testing) and the user locale.

• The first issue is that testing doc is only in English (en) hence for non english environment (including American English - en-US), a "404 NOT FOUND" error is by default returned. And we do not propose en language in qgis locales settings. So except those whose locale system is en, it will fail for most of us.

• if the language does not exist, we should return the english version (which will "unfortunately" (?) be the case for a long moment given that no 3.x doc is going to be released soon)

• [] Because 3.0 and neither 3.2 are LTR, the first QGIS3 documentation released (and translatable) will be 3.4 (in july 2018). What do we offer to non-english people until there?

• [] once 3.0 is released, 3.1 will match testing. Which link will a 3.0 button return? Still testing, which might contain at some point features from 3.1, 3.2 ...? Or should we rely on an older, translated but not fully featured doc, i.e 2.18?

• [] Question: Is that possible to have testing doc somehow translated without pushing it to transifex? I mean we pick translations from the released branch (e.g. 2.18) and show them in a testing doc (with a language selector combobox)? Of course that document will be a mix of english and localized language (where strings match).

• [] QGIS Desktop relies on full hyperlink to doc page, hence uses the section title. Because new features are continuously added, current title of sections/chapters can become inappropriate (too restrictive e.g), hence changed --> Risk of a #404 page. Also, due to docs restructuring, sections can move and break links (see eg https://github.com/qgis/QGIS/pull/4941). So, Is that possible to use the internal link of sections (which has likely no real reason to get changed)?

• Be able to open the doc according to the active tab in case of multi tabs dialog: e.g., assuming the user has opened the vector layer properties dialog, Diagrams tab and clicks the Help button, open the browser on the Diagrams section instead of simply the vector properties chapter (rather the application level issue? would that be possible? Would that worth the effort?) -- to do in the application (has been done for Options dialog in https://github.com/qgis/QGIS/pull/5245)

• [] Provide a help button in most of the dialogs, as long as it makes sense and is possible (see https://github.com/qgis/qgis3_UIX_discussion/issues/33 and https://github.com/qgis/QGIS-Documentation/issues/1926)

• [] Maintain a list of correspondence between Desktop help buttons and doc webpage (seems that should be done at doc level - https://github.com/qgis/QGIS/pull/4023#discussion_r96844564) -- Updates: Work in progress: see http://osgeo-org.1560.x6.nabble.com/Qgis-community-team-Let-s-bring-documentation-at-the-heart-of-QGIS-Desktop-td5329752.html but HELP needed

• [] Add a "Report Documentation issues" to the Desktop Help menu, to ease report of missing or dead links

Improve Doc Server behavior

• If someone wants to go to http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/vector_properties.html#provide-an-ui-file and the last bits of the link (provide-an-ui-file) is no longer accessible, the link should fallback on http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/vector_properties.html. This will strengthen link to QGIS Desktop, avoiding 404 page in case of broken link

• If someone wants to go to http://docs.qgis.org/testing/fr/docs/user_manual/working_with_vector/vector_properties.html, instead of returning a NOT FOUND page, it would be nice to fallback to the english version of the page ie, http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/vector_properties.html (see section above for more concerns)

• [] Tackle the use of double slash (/) in the hyperlink (eg, http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector//vector_properties.html): do not return an unformatted page (see https://github.com/qgis/QGIS-Documentation/issues/1675)

• [] Avoid online search tool (e.g. Google) returning 2.2/2.6/2.8 pages instead of more recent doc release when looking for a doc page

• The search bar: make it powerful and using localized expression; Results should be relevant and ordered by relevance -- with python3 and upgraded sphinx, this has got some improvement though there still is an issue

• [] Improve doc build time: caching files?

Update PyQGIS Cookbook and Training manuals

With a priority to PyQGIS Cookbook

Separate release-related documentation from "static" one

See http://osgeo-org.1560.x6.nabble.com/Qgis-community-team-Management-of-release-independent-documents-td5318107.html

Other improvements (if not done meanwhile)

• [] New identity of QGIS Website and Documentation (frame, color, fonts in relation with new logo ?)

• [] Add translated rate to QGIS webpage

• [] Figures numbering

• [] Fix PDF documentation

• [] Reduce top margin of some section title (level 2 & 3?) and increase font size of some section title (level 4)

• [] In translated doc, text size and margin, especially in lists, are not the same than english one

• [] Structure something that ensures QGIS Documentation spends its budget: what do we need...

• [] Improve set of sample data with dxf or dwg files

• [] Create an issue report template to avoid invalid reports (explaining what this repository is about, asking whether the issue is about the online doc, the link to the section concerned...)

For website

• [] Add rate of translation for each language and QGIS project from Transifex

• [] Discuss need of publishing a blog post to advertise when new case study is added. Those are very valuable information that I'm afraid few people are aware of

Attract new writers

A lot has already been done to help new contributors ( a detailed doc guidelines, including a step-by-step process for first git/github contributions). While a git Faq was planned (see https://github.com/qgis/QGIS-Documentation/issues/1270), I'm no longer sure it's the way to go, it's worth the effort. Git issues will be fixed when raised by.contributor. However, we can:

• [] Make an excessive use of the easy label to filter the numerous issues generated for 3.0. We need to focus on big issues and if we can indicate to beginners what they could easily work and get their help, it'd be nice

• [] Add to the easy issue reports a tip on how the issue could be solved. This will give some help, guidance and confidence to newcomers

• [] (don't know if it works but...) Create a "First contributions" label (until the writer has 5 pull-requests merged) - it could emulate people trying to leave that beginner's status (let's dream).