-
Notifications
You must be signed in to change notification settings - Fork 361
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Possible updates to the documentation #6687
Comments
All good points, Paul. There's also the user script contributions page - https://docs.generic-mapping-tools.org/dev/users-contrib-scripts.html. Since there's only one this could either merged into examples or moved to the showcase on the forum. But does that example still work? I'm not sure based on https://forum.generic-mapping-tools.org/t/vertical-slice-in-a-3d-map/2875, but haven't checked. Regarding a PyGMT tutorial, I think it would be better to have a link to the product of GenericMappingTools/pygmt#770 hosted in the PyGMT docs rather than maintain tutorials in Python in multiple places. It would be easy to have link work with your suggestion of a 'Tutorial in Python' item in the sidebar. Regarding development versus governance, do we have anywhere public that lays out the governance tasks to be accomplished as part of the NSF grant? I think the governance documentation would be most effectively discussed in that context. Under getting started, I would add a link to installation instructions, even if it just redirects to https://github.com/GenericMappingTools/gmt/blob/master/INSTALL.md. |
I agree with @maxrjones that we should put GMT install instructions in the docs (under getting started), rather than in the root directory of the repository or the source tarball. For users who are new to GMT, it's more likely they will read the docs for install instructions rather than looking into GitHub or the source code. |
Looking the the sidebar of the dev documentation (http://docs.generic-mapping-tools.org/dev/), here are my thoughts.
Instead of having four tutorials on the sidebar
I think we can have a single "Tutorials" entry, which is a page that lists the four tutorials. On this page, we can also add one short paragraph explaining why we have four tutorials (new GMT users may have no idea of core GMT and its wrappers). It also makes the sidebar shorter.
I agree.
I'm not sure about this. Do "Code of Conduct" and "Team Gallery" belong to "Governance". Actually, I'm thinking if we should move the "Team Gallery" to https://www.generic-mapping-tools.org/? For common options, we have separate pages for modern and classic modes (http://docs.generic-mapping-tools.org/dev/std-opts.html and http://docs.generic-mapping-tools.org/dev/std-opts-classic.html). Instead of having two pages, maybe we can merge the classic one into the modern one? Below the big table of the modern common options, we can add a small table to list classic-only options (i.e., -K, -O, -P) and also mention that -l is modern-mode only. After merging the two pages of the common options, in the "Classic Mode" category, only the "Module (classic mode)" is left. Maybe we should move it to the bottom of the "Reference Documentation" category? |
Agree on the tutorials page. The reference section has things a user will need, while the PSL etc is only for developers. I think we want to keep the user docs separate as they have no need to see the other things Agree on reducing the common option pages. Hard for anyone to see the difference between the two tables, so one table plus an addendum for OKP and a note about -l will be much better. |
Should we remove the "Users script contributions" and "Users symbol contributions" from the docs? The script is not actively maintained, and the "symbols" are rarely used. To keep a backup of the script and symbols, we can move them to a standalone repository. |
Ping @PaulWessel @joa-quim and @GenericMappingTools/gmt-docs |
I agree. |
A separate repository is ok with me, with a link from the main site? |
Sorry but I don't see the need for a change. Right, the "Users script contributions" dodn't work and I'm not against moving it into buried place or even remove the category all together. But hiding the "Users symbol contributions" I'm not favorable. |
Thinking some more I see the difference; I’m joining @joa-quim here. The symbols are useful for some users whereas the script donations may not be. We have the forum |
Looking at the documentation webpage sidebar I had these thoughts:
Under Getting Started we have
The first two are both galleries of sorts. Both are examples as well, so the naming is a bit inconsistent to me. Then there is a tutorial and another one in Julia. What is the first in, one may ask, etc. My suggestion:
Illustration Gallery
Animation Gallery
Tutorial in bash
Tutorial in Julia
[Might there be on in PyGMT?] How about GMT/MEX? Maybe for the latter we should add a link to the pre-publication version of the GMT/MEX G-cubed paper (which we foolishly did not do Open Access).
Next is Reference Documentation. Pretty good, but would not the API and PostScriptLight documentation fit in better here as well?
Finally, Development seems to mix actual development things with aspects of governance. Maybe these should be separated out better? Maybe a separate About section that is moved to the top?
The text was updated successfully, but these errors were encountered: