(mistakenly sent a previous unfinished message. sorry!)

Wow.... Very impressive and detailed comments! I like that. You had a full
weekend... Sometimes we are used to the way things behave (even if wrong)
so that some fixes could be postponed or neglected. Having this kind of
reminds from a new user is really useful.

I'm not a developer per se so I let devs react on their side. But on a
general side, I feel that there are some of these issues reported in
http://hub.qgis.org. But a recall is still worthy. Others are also already
fixed in the upcoming 3.0 or being addressed (give a look to
https://github.com/qgis/QGIS/pulls for improvements). Also note that while
the UX mailing list has been closed for the reason Anita exposed, we had
opened a repository to collect all UI/UX issues that should be addressed
before 3.0 release. Inputs are welcome so Feel free to complete the list at

As a Doc team member, I'll rather comment that side of your message. As
Nathan pointed out, this is mainly currently written by volunteers, on
their free time and we are still looking for contributors:
- No need to be a QGIS expert: simply know what you are writing about
- No need to be English native (none of us is currently but one would be
very welcome) nor a novelist: together, we'll try to fix and write the
"best" english possible
- No need to know all the documentation structure nor contents: if you feel
some information is missing at some place, just report it or, better,
propose your help to add it. Otherwise, new features to add to the
documentation are listed at
https://github.com/qgis/QGIS-Documentation/issues; pick the one you wish to
document and go ahead.
Doc writing instructions are available at
http://docs.qgis.org/2.14/en/docs/documentation_guidelines/ and the team is
present if needed.
The qgis-community mailing-list is also a good place to discuss
documentation matters.

This was an *overall call for documentation contributors*.

Back to your comments, John, As I earlier said, i welcome your comments
because we are all nose to the grindstone and sometimes do not see some
obvious issues.
While I agree that dev list is the best place to discuss fix matters, I'm
glad to see this report here

> * Where the are the QGIS 2.18.3 release notes? They are not easy to
>   find from the website. It's easy to get to
>   http://qgis.org/en/site/forusers/visualchangelog218/index.html
>   but that doesn't cover the "dot" releases. Other links take you to
>   http://hub.qgis.org/projects/quantum-gis
>   which is not so helpful, at least not directly.

Weird, whick links sent you there?

>   Is there nothing more user-friednly than the ChangeLog? If not, at least
>   someting should link to the ChangeLog:
>   https://raw.githubusercontent.com/qgis/QGIS/
> 382e70ed98ba7b498d9501c0746ff81cfb958611/ChangeLog
> Agreed. There should be a link to the changelog available. This is a
frequent request.

> % After I drafted the outline that led to many of the issues in this
>   email, I figured I had best go through the QGIS documentation to see
>   if I was missing anything totally obvious, and to give it a similar
>   level of review. I think my patience for doing so fell off
>   exponentially after the first 100 pages, however. And this is
>   against the QGIS 2.14 PDF (sorry).
* CRS on first reference. On p.32 is the first time it talks about
>   a CRS, but never explains it is a reference system. Acronyms should
>   be expanded on first reference (and possibly more than that in a
>   manual prone to random-access use.)
> Agreed again (should be easily fixed) but keep in mind that documentation
is an iterative work, not really linear and we unfortunately do not keep
eyes on first appearance of expressions. Maybe this is technically
feasible. Also note that besides the user manual, we have a "Training
manual" and an "Introduction in GIS" documents. But of course these do not
dispense us to explain these expressions.
We recently discussed about a glossary but not easy to build/maintain given
the current striking force.

> * Apple's OS is properly "Mac OS X" shortened to "OS X" not
>   "OSX". (But I guess they're trying to rebrand as macOS). Docs
>   should be consistent and use "OS X" everywhere, not "OSX" sometimes.
> Easy fix

> * The use of the X symbol for |osx| is not a good choice, I fear.
>   http://docs.qgis.org/testing/en/_images/osx.png
>   It's nonstandard, it's doesn't trigger "Mac" in most people's minds.
>   And worse, it does seem extremely reminscent of the X windows X.
>   Probably that doesn't confuse Linux people who are tied to their
>   penguin, but us old-timey non-Linux Unix/X11 people kind of cringe.
>   Compare with https://www.x.org/wiki/logo.png
>   I think a better symbol would be Apple's apple logo
>   https://developer.apple.com/favicon.ico
>   I'm sure that'd be fair use, also...
> I've been puzzled by this too. I think it should be easy to fix (unless
there are some licensing issues?).

> * I'm probaly being hypersensitive, but I found this text in
>   preamble/conventions.rst to be, well, kinda offensive:
> Larger amounts of text may be formatted as a list:
> |nix| Do this
> |win| Do that
> |osx| Do something else
>   It can be read to imply that everybody should use Linux ("Do this")
>   or Windows ("Do that") but not MacOS ("Do someting else"). I realize
>   it wasn't meant that way,  but it should probably be reworded ("Or,
>   do this.")
No bashing intent, I'm sure. Fixed now (note that fixes are done in the
testing documentation and not the 2.14 doc)

> * Section 8.4 refers to the eyedropper tool as a "color picker". This
>   is confusing and incorrect. A "color picker" is a complex GUI widget
>   that lets you choose any color using sliders and number boxes, etc.
>   https://en.wikipedia.org/w/index.php?title=Color_picker
>   https://developer.apple.com/library/prerelease/content/
> documentation/UserExperience/Conceptual/OSXHIGuidelines/
> ControlsandViews.html#//apple_ref/doc/uid/20000957-CH108-SW8
>   It is not a tool that lets you pick up a single color from a point
>   on the canvas. That's usually called an eyedropper -- which is what
>   the icon is.
> This is the wording used in the application itself. Should therefore be
fixed in both.

> * Section 8.5 Blending modes doesn't put "soft light" in boldface like
>   the others.
> Not sure I understand what you mean. Looks the same afaics.

> * Section 8.7 Measuring doesn't expand UTM (Univeral Transverse
>   Mercator) on first reference. And the expansion probably doesn't
>   help most people, it probably needs a gloss?
> see above

> * Through the manual, settings are accessed via "Settings". But under
>   OS X, you get there with QGIS > Preferences...
> I think it's also accessible through Settings menu under os x (no mac
available right now to check). We try to mention when there are platform
specific command/behavior (
but this require someone to have access to that platform

> . And the Title Bar of the Preferences window identifies it as
>   "Options." As if were weren't confused already!
> . If this is platform-specific there should be a note about it. Maybe
>   a macro. I guess there is a note in 7.1.14, but I didn't find it
>   while reading.
> * Ctrl-$foo under Win/Linux is Cmd-$foo under OS X. The manual should
>   acknowledge this somewhere, though maybe not everytime. (But maybe
>   it should everytime? Because Macs do have Ctrl keys and they are
>   available but do something slightly different. So...)
> right! This should become a reflex for writers to not confuse mac users.

> * Sec. 4.1, View Data, talks about WMS and WFS without expanding or
>   explaining them.
> . Maybe this is an unfair criticism because it does the same for OGR
>   and ESRI, as well as SDTS and JPEG. But none of those bother me?
> A glossary?

> * Sec. 12.1, s/driver/drivers/: "You should note also that some driver
>   doesn’t support"
> fixed in testing doc. I won't comment the other typos issues. Some are
already fixed (in Testing doc) or should be done (only needs time and
hands). Thanks for the catch anyway!

> [...]
> * It seems like there is something consistently wrong with the figure
>   crossreferencing code throughout the document. For instances, we
>   often see text like "The Feature filtering dialog of the attribute
>   table provides the following functionalities (see
>   figure_composer_table_4):", but then the figure underneath is
>   labelled "Figure 19.33: Attribute table Feature filtering Dialog."
> . It seems like "figure_composer_table_4" is an internal label that
>   should not be shown to the user.
> . I'm not sure if it should be expanded as "(see Figure 19.33)" or
>   more completely as "(See Figure 19.33: Attribute table Feature
>   filtering Dialog)." Probably the latter?
> Yes this is linked to an internal organization of the documentation we are
trying to get rid of and which also requires to upgrade the Sphinx version
we are using to build documentation. It's a work in progress. Note that the
automatic placement of the figures in the PDF (managed by LateX) does
neither ease the reading.

> [...]
> * 12.3.2: "2.5 D" is used without defining it? I think it's a concept
>   worthy of a few words.
> . Also, in the shapefile context, the docs say “2.5D”? Since I more
>   commonly see "3D" or "3-D" than I do "3 D," I would tend to think
>   that "2.5D" is correct and the usage should be made consistent?
>   The AHD says 3D or 3-D: https://ahdictionary.com/word/search.html?q=3d
>   M-W says 3-D: https://www.merriam-webster.com/dictionary/3d
> Consistency is always a good way to go.

> * Figure 12.26: In the 2 images on that figure, it would sure help to
> highlight
>   visually the differences between them.
> Imho, images should be enough; if it's not obvious, then the figures are
not good enough.

> [...]
> * Chapter 19: the Print Composer. I am confused why this chapter comes
>   so late in the book, after estoteric scripting stuff? I think most
>   QGIS users want to print (or output to PDF), but far fewer are going
>   to tackle batch processing, GRASS, etc. I'd think printing should
>   come as soon after vector and raster data as reasonble (maybe, for
>   parallelism, it has to come after OGC and GPS data too? But I don't
>   think so...)
> I do not share the analysis about proportion of users willing to print or
make analysis but i agree that the Print Composer chapter should be closer
to layers symbology chapters and not separated by processing stuffs.

> And that's all, folks.
> If you made it here, you get a special prize!

Where's my prize?? :-)

Thanks for your contribution and looking forward to fixing/discussing them
with you on mailing lists, or bug trackers.


> --jh...@mit.edu
>   John Hawkinson
> _______________________________________________
> Qgis-user mailing list
> Qgis-user@lists.osgeo.org
> List info: https://lists.osgeo.org/mailman/listinfo/qgis-user
> Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-user
Qgis-user mailing list
List info: https://lists.osgeo.org/mailman/listinfo/qgis-user
Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-user

Reply via email to