(mistakenly sent a previous unfinished message. sorry!) Hi, 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 https://github.com/qgis/qgis3_UIX_discussion/issues 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 * DOCUMENTATION ISSUES: > > * 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 ( http://docs.qgis.org/2.14/en/docs/user_manual/introduction/qgis_gui.html#qgis) 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. Regards, Harrissou > > --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 Qgis-user@lists.osgeo.org List info: https://lists.osgeo.org/mailman/listinfo/qgis-user Unsubscribe: https://lists.osgeo.org/mailman/listinfo/qgis-user