forked from qgis/QGIS-Documentation
-
Notifications
You must be signed in to change notification settings - Fork 0
On the road to QGIS3
Harrissou Sant-anna edited this page May 31, 2017
·
18 revisions
Ideas to structure the next QGIS documentation generation
- Place this chapter out of the Vector chapter and make it as first level chapter (near Vector, raster... chapters)
- Would be nice to merge all the sections related to opening data (see https://github.com/qgis/QGIS-Documentation/issues/1088)
Links to doc sections are added to QGIS Desktop context 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 ideas below:
- Need to check if there's a default doc link added to QGIS3? What could that be?
Proposal in case nothing is done in this sense (afaics): have a dynamic link that will use the current QGIS version in the link.
- if the version matches a released doc version (e.g. 3.2), nice
- if it doesn't match any released doc version (e.g. 3.4), should we use testing ( i.e. 3.6) link or the version released before that Desktop version (i.e. 3.2)?
- 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. So, Is that possible to use the internal link of sections (which has actually no 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?)
- Provide a help button in most of the dialogs, as long as it makes sense and is possible
- 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)
- Given that 2.18 doc will be translatable while 3.x doc will only be released and translated for 3.2 (9-12 months later), it'd be nice to have 2.18 doc follow the 3.x doc structure. Why? To ensure that link will fall back from
- 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
- 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 when looking for a doc page instead of more recent doc release
- The search bar: make it powerful and using localized expression; Results should be relevant and ordered by relevance
- Improve doc build time: caching files?
With a priority to PyQGIS Cookbook
- 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
- 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