-
Notifications
You must be signed in to change notification settings - Fork 0
Processing Help structure: what do we write...
Hi,
Processing help is being rewritten. Some PRs have been already proposed, reviewed and merged. The general structure of the help of an algorithm has been set through discussion. However, this knowledge of the already made decisions is nowhere available, unless inspecting pull requests discussions. This makes pull requests review hard because reviewer is not always sure whether this content should be put there or not, if that hadn't been already discussed and he can even become schizophrenic, asking something here and the opposite few lines later...
This is an attempt to formalize the algorithm help. It could sound bureaucratic for some of us but a reviewer should not be lost when contributing, should not worry about his comment contradicting any previous decision or being too much exigent for the writer. So i personally need it and am convinced that it'll improve things:
- everybody knows what has to be provided for each section, hence reviewing will just help to improve text instead of discussing whether it's a place for an information or not
- we can quickly identify what is missing
- we avoid repeating same demands
- we avoid asking a change in one place and its contrary few lines later
- we ensure the same structure, not only for section titles but also in the provided contents
- we help users to identify the sequencing of information
- we can reuse sentences, helping translators to minimize their effort and easily figure out the context of translation
- it could be reused as Processing help guidelines
- …
Decided
- Add an anchor at the top of each algorithm, built based on the following sequencing: provider_namewithunderscore ie
qgis_bounding_boxes,qgis_buffer... Is that naming compatible with what is expected from the QGIS application help system? - Name the algorithm like in the application
Question
- For the algs that have a dedicated icon, do we add one near their name (see https://github.com/qgis/QGIS-Documentation/issues/2216)?
- Pro: it will help user to quickly identify features
- Cons: it may appear in the table of contents. Is that undesirable? Or is there a way to hide it?
- Some algorithms description begins by
Creates a new vector layer that ...while others, even though they might generate new layers do not mention that. - I think when it does not create a new layer, it's mentioned (but I must confess that I didn't check them all)
It's not always mentioned whether the algorithm creates a new layer or not. I think we should either -
A description should mention the following information
- what it does: a first short sentence specifying the operation that is done, the kind of expected result.
- more information whether it uses some variables
- whether it creates a new layer or not (we should try to reuse the same sentence)
- try to reuse existing sentences
Some examples below
Calculates the bounding box (envelope) of each feature in an input layer. Polygon and line geometries are supported.
--> Does it create a new layer? With or without geometry? We can't tell here.
some good ones?
Takes a polygon layer and removes holes in polygons. It creates a new vector layer in which polygons with holes have been replaced by polygons with only their external ring. Attributes are not modified.
Performs a validity check on the geometries of a vector layer. The geometries are classified in three groups (valid, invalid and error) and a vector layer is generated with the features in each of these categories.
- In some algorithms, particularly those involving two layers in input, the name of the second input layer is not really clear; sometimes it's the same as the output (eg, intersection algorithm). Given that we are using the same vocabulary as in the application, this is an application issue
- some parameters descriptions look like tooltip, eg `Choose
Each parameter used by the algorithm should be mentioned with type of values (and default value if concerned)
We should avoid description like
Input Layer[vector: any]Input vector layer
and prefer description like
Input Layer[vector: any]Vector layer to select the features from
Geometry predicates: Do we need to list them for each algorithm? Could be nice to have a place (in Processing intro) to describe what they really mean (eg, can A be within B if they share boundary but all A interior is in B?) Explain what QGIS vs GEOS for geometry check means
What are the rules for screenshots:
Screenshots should be simplest possible and self-explanatory
- Size: is that configurable?
- Colors: would that be better to use less colorful and shiny pictures?
- Geometry: Would that be better to use real features or just simple regular geometries? Looking to ArcGIS or PostGIS docs, they use simple shape for their illustration...
- are there particular rules on screenshot we can raise here?