Skip to content

hackfest_Bonn_2016

Jump to bottom Edit New page
Jacolin edited this page Aug 22, 2016 · 29 revisions

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

Topic:

Some parts are probably too obvious to describe it in the doc, how can we describe the limit between something to describe or not?

Decision:

We should decide case by case.

getting_started vs gui vs other part

Topic:

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.

Decision:

  • 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

See https://github.com/qgis/QGIS-Documentation/issues/1334

Reorganising the Supported Format Data chapter

Topic:

http://docs.qgis.org/testing/en/docs/user_manual/working_with_vector/supported_data.html

Decision:

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

Topic:

See http://hub.qgis.org/issues/9483 and how? Does it make sense? what are the impacts on the current structuration? See QEP #32

Decision:

Improve documentation writing and reading

[Later] Improving the use of Index

Topic:

See:

Decision:

  • 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

Topic:

Move picture files in a subdir of the chapter.

see https://github.com/qgis/QGIS-Documentation/issues/793#issuecomment-231805559 ?

  • YJN: +1

Decision:

TOC and GitHub preview

Topic:""

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)

Decision:

Expandable TOC in doc panel

Topic:

Having first level sections exposed in the left panel of the doc when a page of a chapter is being read could be useful

Decision:

  • YJN: +1

Training manuals

topic:

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?

Decision:

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

Topic:

see https://github.com/qgis/QGIS-Website/pull/343

Decision:

Do you think adding a number in the reference for figure is a good step

Topic:

Update is a bit painful (see https://github.com/qgis/QGIS-Documentation/pull/1191)

Decision:

  • YJN: 👍

Empowering Contributors

Translated Doc and Website often fail to build due to errors in translation

Topic:

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:

Decision:

learning how to do translations

Topic:

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.

Decision:

Documentor wall of fame

Topic:

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:

Decision:

Commit rules

Topic:

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)

Decision:

Attract more contributor

Topic:

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.

Decision:

Linking doc and website pages

Topic:

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)

Decision:

People

Please, add yourself below.

  • Yves Jacolin
  • Harrissou Sant-anna
  • Alexandre Neto
Add a custom footer
Clone this wiki locally