Bonn Hackfest 2016
This page aims to list topic to discuss at the Bonn Hackfest. Feel free to list anything you want to discuss.
Structure the documentation
How to improve the structure of the doc to allow more features in the long term?
[Later] What needs to be added in the documentation
Some parts are probably too obvious to describe it in the doc, how can we describe the limit between something to describe or not?
We should decide case by case.
getting_started vs gui vs other part
See https://github.com/qgis/QGIS-Documentation/pull/1185#issuecomment-231676701: what do we put in some (generic) title?
- guidelines: Add description at the file header for each chapter: For instance, getting_started chapter aims to show a quick and simple how-to to add a simple layer and make some change.
- GUI: only the interface of the default QGIS
- getting start: a short introduction to add a vector and raster layer and identify one feature. Nothing more.
- general tools: tools that are not linked specifically to vector, raster, of a specific chapter
Reorganising the Supported Format Data chapter
- describing each dabatase dialog is a bit redundant. Better summarize the dialog description in a single place and add notes about particular situations? This will also help format that are currently not really described (such as MSSQL)
- Find a better place to the http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/supported_data.html#vector-layers-crossing-180-degrees-longitude section
See comments that list decision in the following discussion here https://github.com/qgis/QGIS-Documentation/issues/1088
Could there be a relation between documentation and Context help in the application
See http://hub.qgis.org/issues/9483 and how? Does it make sense? what are the impacts on the current structuration? See QEP #32
Improve documentation writing and reading
[Later] Improving the use of Index
- hidden page: http://docs.qgis.org/testing/en/genindex.html
- Doc: http://www.sphinx-doc.org/en/stable/markup/misc.html#index-generating-markup
- preference between the use of
- Avoid inline tags to improve readability of the text
- Add guidelines
- We should clean up index page (remove _ between words, get a capital letter at the begining of the word)
Screenshot and Github preview
Move picture files in a subdir of the chapter.
- YJN: +1
TOC and GitHub preview
Would be nice to get back TOC in GitHub preview without having them in PDF files (see https://github.com/qgis/QGIS-Documentation/issues/1155)
Expandable TOC in doc panel
Having first level sections exposed in the left panel of the doc when a page of a chapter is being read could be useful
- YJN: +1
Who is(are) in charge and (how) is it really up to date (seen few PRs)?
- Same questions for Python cookbook
- The "A Gentle Introduction in GIS" document: future of a somehow outdated (at least for QGIS screenshots) doc? Relation with Training manual?
We decide to focus on user manual and work on this when we have enought time (Around the 3.0 release probably)
Move the Install instructions to doc or website
Do you think adding a number in the reference for figure is a good step
Update is a bit painful (see https://github.com/qgis/QGIS-Documentation/pull/1191)
Translated Doc and Website often fail to build due to errors in translation
This situation doesn't benefit to the readers (and thus the QGIS Project) given that people are offered older work and translators are puzzled to not find their work available. Fixing those build errors can be very time-consuming and the current process to do it (build the doc from source --> note the errors --> find them in Transifex --> fix them --> Rebuild to ensure everything is ok) is not within anyone's reach. But this can't be done by few people (for all languages). Translators can be associated with fixing those errors by:
learning how to do translations
We need a way to ensure everyone has read at least http://docs.qgis.org/2.14/en/docs/documentation_guidelines/do_translations.html#summary-rules-for-translation (or the whole page) --> Is there a way to have a link on our Transifex page?
- providing them a page (on qgis.org? accessible through a link from the date of last build at the bottom of the index page) where build errors can be automatically reported. Translator will then only need to fix the text in Transifex and then wait for next build time.
Documentor wall of fame
While developers and translators of QGIS applications are cited in the About panel of the application, doc and website writers and translators are not mentioned anywhere. There's an outdated list in the readme of each repo but they may "deserve" a better presentation (see idea at https://github.com/qgis/QGIS-Documentation/issues/669), either:
- in the About panel of application
- in a special acknowledgment page in the website or at the end of doc
- It can also be more visibility of https://github.com/qgis/QGIS/blob/master/doc/contributors.json, combining all kind of contributors
Position about direct commits to branches, without PR: some committers directly push their changes to the doc without using a pull-request. While this could not be a problem and may be done for simple/obvious minor changes, this has some problems when done on a consequent range of texts:
- no review from others: risk of typo error, incomplete description, not the best place...
- risk of breaking silently the build
- A PR is also a way to inform the others about what is put in the doc (I often learn QGIS from the PR - I think i'm not the only one)
Attract more contributor
More ideas to improve the doc guidelines and attract more (long term) contributors: add a FAQ to help people go through the twists-and-turns of git.
Linking doc and website pages
What is the best way to add hyperlink of doc page in website page (and vice-versa)? see the last paragraph of http://qgis.org/en/site/getinvolved/document.html#becoming-a-documenter. The documentation guidelines hyperlink send to testing doc but it should rather be a translatable one (2.14) but moreover, it should not be static nor untranslated, meaning that if 2.16 doc is available it should point to that one (to have the most up to date guidelines) and in hungarian if the website was in hungarian The other direction example is http://docs.qgis.org/2.14/fr/docs/user_manual/preamble/whats_new.html which then sends you to a changelog in english, while one would expect something still in french (given it's still a QGIS page)
Please, add yourself below.
- Yves Jacolin
- Harrissou Sant-anna
- Alexandre Neto