Improving user documentation

[KristofKoch]

The current docs (-B for example) are loaded with information in comparatively few lines. This is not always easy to understand. There was some discussion in the past what to do with the man pages (where those densely packed pages originated from) and the Cookbook.

My idea is to keep the man page in their current dense form and move the example section to the Cookbook and expand it there with a lot of examples in code and graphics. Basically

• Man-Page for the power user (cheat sheet on how to call that program)
• Cookbook for in-depth explanation with lots of examples (beginner friendly)

In my eyes this would avoid the current problem of the man pages getting littered with (too few) examples which don't fit my problem and the Cookbook not tackling all aspects. The things explained in the Cookbook are great. Mostly adequate depth of detail, you see the code and the result and you can get some tips on solving special problems even when external programs are necessary.

What do you ladies and gents think @GenericMappingTools/core?

[WalterHFSmith]

I concur. Walter H F Smith Geophysicist, Laboratory for Satellite Altimetry NOAA NCWCP code E/RA-31 5830 University Research Court, room 3752 College Park MD 20740-3818 301-683-3377 (voice, my desk) 301-683-3300 (voice, reception) 301-683-3301 (fax, reception) Walter.HF.Smith@noaa.gov http://www.star.nesdis.noaa.gov/star/Smith_WHF.php

…

On Jan 21, 2021, at 2:45 PM, KristofKoch ***@***.***> wrote: The current docs (-B for example) are loaded with information in comparatively few lines. This is not always easy to understand. There was some discussion in the past what to do with the man pages (where those densely packed pages originated from) and the Cookbook. My idea is to keep the man page in their current dense form and move the example section to the Cookbook and expand it there with a lot of examples in code and graphics. Basically • Man-Page for the power user (cheat sheet on how to call that program) • Cookbook for in-depth explanation with lots of examples (beginner friendly) In my eyes this would avoid the current problem of the man pages getting littered with (too few) examples which don't fit my problem and the Cookbook not tackling all aspects. The things explained in the Cookbook are great. Mostly adequate depth of detail, you see the code and the result and you can get some tips on solving special problems even when external programs are necessary. What do you ladies and gents think @GenericMappingTools/core? — You are receiving this because you are on a team that was mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[joa-quim]

I fear.
I fear that the CookBook gets too filled and stuff and users don't find the things there. My preferred example are the detailed info about reading complex netCDF and HDF grids via GDAL that we have in Reading more complex multi-band IMAGES or GRIDS and that people often have troubles in finding it.

[maxrjones]

I like the idea of having more explanation for the many ways to use options like -B and agree that the man pages are not the best place for that explanation. I also agree that it would be helpful to see the code that produces figures in the cookbook. For example, I think it would be helpful to see this code:

gmt basemap -R-2/1/0/0.35 -JM4i -Bpa15mf5mg5m -BwSe -Bs1f30mg15m --MAP_FRAME_TYPE=fancy-rounded \
		--MAP_GRID_PEN_PRIMARY=thinnest,black,. --MAP_GRID_CROSS_SIZE_SECONDARY=0.1i \
		--MAP_FRAME_WIDTH=0.075i --MAP_TICK_LENGTH_PRIMARY=0.1i

above this figure in the cookbook.

I disagree that the examples should be taken out of the man pages entirely, because those examples likely do help users quickly find information that they need. In addition, most software include some small number of examples in the reference documentation and I think it is good to include expected components in the man pages.

For completeness, other changes that I think are necessary are adding how-to guides, revising the tutorial, and adding more cross-referencing between the man pages, how-to guides, tutorial, and cookbook. I see the amount of explanation included as the main difference between the cookbook and the how-to guides/tutorial. The cookbook can include ample information about why things might be a certain way, but the how-to guides and tutorials should be more goal oriented.

[KristofKoch]

Any more comments on this? Maybe @PaulWessel has some thoughts as well?

Hi @joa-quim, I see your point in the forum currently. Maybe the user seeking help did search the docs for "read netcdf" and had no luck? From personal experience I can say that the search function of the documentation is good if you know what you are looking for but is hard when you don't know exactly what your solution might look like. Additionally the current documentation system has a learning curve for how to find stuff.

If you are interested in what that -B does in a snippet of code you found somewhere? Unfortunately, the search function is no help here as a quick search for -B shows.

You must

• know that the information you are looking for hides behind the "Common Options" on the index page and
• then find it in the table
• realize you have to click on the small "(…)" at the end of the line to finally get to the info you are looking for.

Or, plan B, find a module that uses -B

• On the index page you should now be interested in "Modules".
• Have no clue which module uses -B, luckily the first entry basemap is a hit
• click on -B
• click on "(more …)" and get yourself to the finish line this way.

Maybe this is a more fundamental problem with organizing the documentation. It just culminates in "users don't find the things there", as you wrote?

Hi @meghanrjones, ok, maybe it is just me and my use cases that the man page examples are seldomly useful for me. But I see your point. And yes, I agree with you that the command displayed above the plot would be helpful.

I would extend it and say every plot in the docs should have its command next to it. Maybe a separate page for each plot with a heavily commented command would be helpful as well? My reasoning is that the example you took is great not only for primary and secondary plot borders but also for offsets and the arrows and labels beneath it.

I totally agree with your last paragraph. Especially with the cross-linking and the different orientations between different types of documentation.

@leouieda once posted the link to the restructuring effort of the NumPy docs which is similar to what we are discussing here. It references "The Grand Unified Theory of Documentation" which somewhat sounds like a blueprint for our problem on hand.

@meghanrjones and @joa-quim what do you think - might this be a solution for the different problems with the current docs?

[joa-quim]

@KristofKoch haven't read it yet.

would extend it and say every plot in the docs should have its command next to it. Maybe a separate page for each plot with a heavily commented command would be helpful as well? My reasoning is that the example you took is great not only for primary and secondary plot borders but also for offsets and the arrows and labels beneath it.

https://www.generic-mapping-tools.org/GMT.jl/latest/frames/#Geographic-basemaps

[KristofKoch]

Maybe we can steal … erhm … borrow from your Julia documentation 😉

[Esteban82]

I think that another improvement should be to add a video tutorial on building GMT from source. In my case it help me just watching this video (in Indonesian so I didn't understand a word).

[PaulWessel]

We can do something similar and I can narrate it in Norwegian since the language clearly does not matter.

[maxrjones]

@leouieda once posted the link to the restructuring effort of the NumPy docs which is similar to what we are discussing here. It references "The Grand Unified Theory of Documentation" which somewhat sounds like a blueprint for our problem on hand.

Yes, I am completely on board with using that documentation system for GMT!

If you are interested in what that -B does in a snippet of code you found somewhere? Unfortunately, the search function is no help here as a quick search for -B shows.

You must

know that the information you are looking for hides behind the "Common Options" on the index page and
then find it in the table
realize you have to click on the small "(…)" at the end of the line to finally get to the info you are looking for.

Or, plan B, find a module that uses -B

On the index page you should now be interested in "Modules".
Have no clue which module uses -B, luckily the first entry basemap is a hit
click on -B
click on "(more …)" and get yourself to the finish line this way.

Maybe this is a more fundamental problem with organizing the documentation. It just culminates in "users don't find the things there", as you wrote?

These (...) links all take the user to the gmt reference docs common options description. There's also the cookbook description of the common options, which I'm not sure whether a newer user would know about. I think an improved distinction and cross-references between these two documents is needed. As a short term fix, do you think replacing "(...)" with something more descriptive (e.g., "(see full description)") would be helpful?

[Esteban82]

I think that, first of all, we could reordered the information in the man-page in order to be more user-friendly.

For example, instead of this (-F from basemap):

-F[d|l|t][+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]][+s[[dx/dy/][shade]]]

Without further options, draws a rectangular border around any map inset (-D; classic mode only), map scale (-L) or map rose (-T) using MAP_FRAME_PEN; specify a different pen with +ppen. Add +gfill to fill the box [no fill]. Append +cclearance where clearance is either gap, xgap/ygap, or lgap/rgap/bgap/tgap where these items are uniform, separate in x- and y-direction, or individual side spacings between map inset/scale/rose and border. Append +i to draw a secondary, inner border as well. We use a uniform gap between borders of 2p and the MAP_DEFAULT_PEN unless other values are specified. Append +r to draw rounded rectangular borders instead, with a 6p corner radius. You can override this radius by appending another value. Finally, append +s to draw an offset background shaded region. Here, dx/dy indicates the shift relative to the foreground frame [4p/-4p] and shade sets the fill style to use for shading [gray50]. Used in combination with -D, -L or -T. To specify separate parameters for the various map features, append d|l|t to -F to specify panel parameters for just that panel [Default uses the same panel parameters for all selected map features].

We could write something like this:

-F[d|l|t][+cclearances][+gfill][+i[[gap/]pen]][+p[pen]][+r[radius]][+s[[dx/dy/][shade]]]

Without further options, draws a rectangular border around any map inset (-D; classic mode only), map scale (-L) or map rose (-T) using MAP_FRAME_PEN. Used in combination with -D, -L or -T. To specify separate parameters for the various map features, append d|l|t to -F to specify panel parameters for just that panel [Default uses the same panel parameters for all selected map features].
The following modifiers can be used:

• +ppen to specify a different pen with
• +gfill to fill the box [no fill]
• +cclearance where clearance is either gap, xgap/ygap, or lgap/rgap/bgap/tgap where these items are uniform, separate in x- and y-direction, or individual side spacings between map inset/scale/rose and border.
• +i to draw a secondary, inner border as well. We use a uniform gap between borders of 2p and the MAP_DEFAULT_PEN unless other values are specified.
• +r to draw rounded rectangular borders instead, with a 6p corner radius. You can override this radius by appending another value.
• +s to draw an offset background shaded region. Here, dx/dy indicates the shift relative to the foreground frame [4p/-4p] and shade sets the fill style to use for shading [gray50].

There are some arguments like -i in coast that are written this way.

[maxrjones]

@PaulWessel and @joa-quim, do you see any reasons against reformatting some of the option descriptions using more lists? It seems to me that this would make the docs more readable.

[joa-quim]

No, on the contrary. I tried a couple of them time ago but was also dissatisfied with RST that added a lot o vertical space between the bullet lines.

[maxrjones]

@Esteban82, would you mind if I try formatting one of these options as a list to look into the vertical spacing situation in sphinx? Or would you prefer to do that?

[Esteban82]

Yes, I think it would be better if you do it. I have no experience with sphinx if the idea still goes on.

I was thinking, that instead of adding this section, I could make an script with a lot of subplot of synthetic surfaces for the showcase in the forum.

[Esteban82]

Just another idea. I think it would be good to create a section with 2D surfaces (like the 1D array). It would be theoretical surfaces that could be helpful to test scripts for example. It should be add in grdmath manpage. If you think that it is good idea I can do it (or at least start).

[Esteban82]

@joa-quim for me it is useful to test new ideas and methods. But, yes, maybe there would be (very) few people interest it on this. Let me know if should I proceed with this idea.

[maxrjones]

One main benefit is for teaching examples (filtering, detrending, etc.). Synthetic datasets are often easier to understand for these purposes than real data. The section would need to be clear. Why do you think the instructions will be cryptic?

[PaulWessel]

The reality is that grdmath has lots of operators that are native in Matlab, Julia, and Python (e.g., MUL, COS, etc), and then a smaller set of of operators that do not exist there (DAYNIGHT, DILOG, KEI, LDISTG, WRAP. etc).

[joa-quim]

I didn't mean to say that the instructions would be cryptic. It's the command to create surfaces that likely would. Just look at the sombrero.

But examples on using the myriad of operators in grdmath, that's a different story.

[Esteban82]

Another use of the synthetic 2D surfaces is to make the background of the figures like the following. It is not important but I think that this would be more useful for most users. For this use, most of the 2D surfaces would be very simple (nothing like sombrero).

What do you think? If you agree, I could:

1. make a figure with several subplot for the forum showcase or a new example in the gallery
2. edit the example 6 of the gallery (and maybe another one).

gmt begin ex19 png
	gmt grdmath -R0/1/0/1 -I0.01 X = lon.nc
	gmt makecpt -Cwhite,50 -T0/1
	gmt grdimage lon.nc -C
	gmt histogram -Bx+l"Topography (m)" -By+l"Frequency"+u" %" -BWSne+t"Histograms" @v3206_06.txt -R-6000/0/0/30 -Gorange -W1p -Z1 -T250
gmt end show

[joa-quim]

There was a time that Paul wanted to create grdmath macros. That could be useful for use when synthetic data is handy.

[PaulWessel]

Macros are fully operational but not supplied nor discussed in great details. I think they are looked for in current dir or .gmt etc.

[PaulWessel]

Nice @Esteban82, I have made a lot of those things in my day. To make this more accessible to mere mortals, perhaps it is best to have a section on how to make 2-D surfaces and why one would want to.

[Esteban82]

gmt/grd math operators:

I have another suggestion. I was seeing the last column (return) of the table of operators of gmt/grd math. There are many operators that I don't understand what they do (like ACSC, BEI, BER, DILOG). I think that in some a more detailed description could be add. Also maybe we could add a link (to wikipedia?) for more complex operators. What do you think? I offer to help.

[PaulWessel]

There are two different things we could try here. Note that the current layout was inherited from previous versions where the entire documentation was generated from lower-level include files. Now we have abandoned that and do things by hand. Possible options:

1. Add more math and equations. Many of the operators do have standard mathematical symbols or expressions and we can now set that easily with <math> statements.
2. As you suggest, add links to Wikipedia for more obscure functions that may require a bit of background.

[WalterHFSmith]

I think better documentation is always a good idea. About linking to Wikipedia, I would recommend instead linking to the DLMF: https://dlmf.nist.gov This is the modern, on-line version of what used to be Abramowitz and Stegun. There are also other sources. We need to be sure that the source we link to defines the function the way we do. I spent a lot of painful time trying to understand why Mathematica and WolframAlpha didn’t evaluate the ALF Q(nu,mu,z) the way I expected. I wasn’t able to understand it until I read F W J Olver’s book “Asymtotics and Special Functions”. If any of you are math geeks enough to want a PDF copy (too many megabytes for email) I will be happy to send it to you. W

…

On Apr 13, 2021, at 4:11 PM, Paul Wessel ***@***.***> wrote: There are two different things we could try here. Note that the current layout was inherited from previous versions where the entire documentation was generated from lower-level include files. Now we have abandoned that and do things by hand. Possible options: • Add more math and equations. Many of the operators do have standard mathematical symbols or expressions and we can now set that easily with <math> statements. • As you suggest, add links to Wikipedia for more obscure functions that may require a bit of background. — You are receiving this because you are on a team that was mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[Esteban82]

I notice that in the synopsis of the docs of some modules (e.g. movie, grdsample, grdimage) there is no link for the -x (lowercase) argument.
Is this on purpose? I saw the rst file but it was more complex that I expected and I am not sure how to fix it (if this is the case). So I decided to ask here.

[PaulWessel]

Where to you see movie missing -x? If I type gmt movie - it is listed, and if I do gmt docs movie it is also listed.

[Esteban82]

Sorry. What I meant is "hiperlink" so I can click on it and go directly to that part in the docs.

[PaulWessel]

No, not on purpose - maybe @meghanrjones can investigate this. In movie the -x is not the standard -x (Open-MP) option and explanation, but it is for grdsample and elsewhere.