overhaul the "Quick start" section in GPlately online doc

[michaelchin]

Hi team,

The "Quick start" section was called "Main objects" before. I changed the section name because I thought we need a "Quick start" section like many other software projects. However, the content in that section does not really look like a "Quick start" right now.

I would like to propose to overhaul the "Quick start".

1. move "installation" section from the main readme to the beginning of "Quick start".
2. create a "helloworld" for beginners.
3. rename the current "Quick start" section back to "Main objects" or "Main classes".

What do you think? @GPlates/gplately-dev

[jcannon-gplates]

move "installation" section from the main readme to the beginning of "Quick start".

👍 And then have a link to it from the Readme. That way there's still an "Installation" section in the main Readme, but it's very succinct. That's a bit like what the pyGPlates Readme does.

create a "helloworld" for beginners.

Sounds good, but I'm not sure what it would do differently compared to the Getting Started notebook that introduces the main classes. One idea of what to do is mentioned below...

rename the current "Quick start" section back to "Main objects" or "Main classes".

I guess the name depends how much we're going to document for the 2.0 release - because that'll all go into the whatever "Quick Start" is called (which goes into gplately.__init__). After 2.0 we'll be using Sphinx, and have separate chapters, as planned in #329.

I wonder if we should just call it "Documentation" and then move everything under "Usage" and "API Reference" (in the main Readme) into it (ie, into __init__). In other words, "Documentation" could have several sub-sections (which are a bit like chapters). It could start with an "Introduction" section, followed by an "Installation" section, and then a "Quick Start" section - which I think is a good name - that contains a helloworld type example perhaps (which could just have a short description of the main classes - kind of like the current "Quick Start" - followed by a link to the "Getting Started" notebook). And then another section for the remaining stuff that was under "Usage", such as pointers to the notebooks, examples, and cli. And we wouldn't need an "API Reference" sub-section because we're already inside the API documentation.

This mirrors somewhat how the pyGPlates documentation is structured. And, when we eventually move to Sphinx, we'll simply just separate those sub-sections into separate ReST files (and fix up the cross-references, etc). And it means we can start working out the chapter structure now (for 2.0) before we even migrate to Sphinx. And later, after the migration, we'll just presumably be adding more details (and maybe a Primer chapter, which is quite detailed, like the Primer chapter in the pyGPlates documentation).

And that way the main Readme is very succinct, and all the detail is in the documentation. The main Readme would just have the introductory bit (ending with citation), followed by "Documentation" (which points to the main heading, "Documentation", in __init__) and then "Installation" (which points to the "Installation" sub-heading in __init__), followed by "Dependencies" (which I think only need to be listed in the main Readme). And that's all.

By the way, the "Documentation" section (in main Readme) can still have pointers to different versions of the documentation (eg, dev, 1.0, 1.1, etc). We just wouldn't need an "API Reference" section anymore, since those doc links essentially already point to the API documentation.

[michaelchin]

Thanks John. All sound good to me.

but I'm not sure what it would do differently compared to the Getting Started notebook that introduces the main classes.

I am thinking of an extremely simple notebook for the helloworld example. NW said the "Main objects" section was hard to understand for a beginner. Maybe we should create something even a 12-year-old(like my younger daughter) can understand, something like this.

[jcannon-gplates]

Sounds good 👍 . I think this could be in the chapter called 3. Minimal working example mentioned here.

[michaelchin]

@dietmarmuller has shared some valuable insight here regarding the "Quick start" section.

[michaelchin]

The quick start notes were provided to us by @dietmarmuller.

To aid the generation of a quick start guide for GPlately that follows generally accepted conventions for the structure and content of such a guide, I attach a set of general notes about how to structure a quick start guide, and a specific suggested example for how to do it.

In any case, at the very least this should make it a bit easier to get going with creating a revamped guide without having to start entirely from scratch.

quick_start_notes.docx

[michaelchin]

Hi @jcannon-gplates and @dietmarmuller.

I think we should do what John has proposed here. We can always refine it when new ideas come out. I just would like to make the changes and see what it looks like.

[dietmarmuller]

Yes, that’s fine. From: michaelchin ***@***.***> Date: Thursday, 20 March 2025 at 11:31 To: GPlates/gplately ***@***.***> Cc: Dietmar Muller ***@***.***>, Mention ***@***.***> Subject: Re: [GPlates/gplately] overhaul the "Quick start" section in GPlately online doc (Discussion #328) Hi @jcannon-gplates<https://github.com/jcannon-gplates> and @dietmarmuller<https://github.com/dietmarmuller>. I think we should do what John has proposed here<#328 (comment)>. We can always refine it when new ideas come out. I just would like to make the changes and see what it looks like. — Reply to this email directly, view it on GitHub<#328 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/ACPHM5AB6PDYXAPNCKIHXAL2VID6TAVCNFSM6AAAAABZGZIYJGVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTENJVHAYTSNI>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[jcannon-gplates]

Thanks Dietmar, the structure of a typicall Quick Start is quite useful.

I noticed it has a Next Steps & Links section, which points to more detailed document.

Which brings up the question of whether that more detailed documentation should be in a separate document, or just different chapters in the same document. I'm thinking the latter. Mainly because it seems most software documentation these days is one big document with separate chapters. And, actually, it's important to have it together because you don't want to specify two URLs everywhere that you might reference the documentation from.

In other words, we have one single "Documentation" (linked via the GitHub Readme, and wherever else links to it) which contains several chapters, one of which is the Quick Start guide (or even move the chapters from Quick Start into it).

It might be useful to also have a link to the Quick Start chapter(s) in the GitHub Readme (in addition to a link to the overall "Documentation"), considering it's importance. I read online that there are two reasons why Quick Start guides are useful:

First that they take ‘less time reading’ and second that ‘If the installation takes place without any hick-up and/or the first user experiences are nothing but positive, self confidence leads to the motivation to explore the product even further.

So the GitHub Readme can be something like:

• Documentation (URL)
  • Quick Start
    To get started, please follow the installation instructions (URL) and try out the minimal working example (URL).

So I think having the first 3 chapters in the main documentation follow Dietmar's Quick Start chapters:

1. Introduction
2. Installation
3. Minimal working example
   • Show a basic, functional example with minimal dependencies.
   • Keep it simple and easy to understand.

...should satisfy getting a first user up and running quickly. Where the Quick Start in the GitHub Readme links to the 2nd and 3rd chapters (a quick start does not need to link to the Introduction, the first user is already sufficiently motivated by now).

Can then add more chapters from Dietmar's Quick Start:

4. Common Use Cases
   • This can cover what is currently in our Quick Start.
   • Ie, a brief description and code example of each of the main classes (5 or so classes).
5. Trouble-shooting and FAQ

And then instead of Next Steps & Links we just continue with regular detailed documentation chapters:

6. Examples
   • Notebooks
   • Other examples (not notebooks).
7. Command-line interface
   • Maybe goes through each command with an example.
   • Could possibly be merged into another chapter.
8. Primer
   • This is like the Reference Manual mentioned below.
9. API Reference
   • This is the main part of GPlately.
   • It's covered very well.

Interestingly, as an aside, I noticed talk online of a Reference Manual, which is even more detailed. For example, the User Guide might just go through steps to do something at a higher level, while the Reference Manual gets quite detailed (basically everything you need to know about doing something). I realised that, in the pyGPlates documentation, the Primer chapter is like the Reference Manual (and the Getting Started pygplates chapter is like a Quick Start, in that it contains the Installation and an introductory tutorial).

[michaelchin]

Hi @GPlates/gplately-dev @dietmarmuller

I have updated the main readme and online doc according to John's advices. Nothing is final. Everything is open to discussion. I just would like to start making changes and get the ball rolling.

PS. I have read this Discussion thread a few times. Every effort has been made to ensure that all points are thoroughly covered. However, if I did miss something, please kindly let me know. Thanks.

[jcannon-gplates]

Looks good 👍

I realize now that we have the issue of whether to point to the stable or dev version of the Quick Start (from the main Readme). I guess it should be dev, but then stable users might get the wrong advice (if dev differs). Conversely, if have stable then dev users might get wrong advice. Mostly thinking of the 'installation' part of the Quick Start.

I guess this suggestion of mine...

• Documentation (URL)
  • Quick Start
    To get started, please follow the installation instructions (URL) and try out the minimal working example (URL).

...is problematic if you have different versions (like we do), and therefore it either gets repeated (with different version URLs) or we only link to the Quick Start under one version (ie, not under all the versions). I guess the latter makes sense (as you're currently doing). Then we just need to decide which version.

Although, I wonder if we should just keep the main Readme simple, and just have links to the different documentation versions? Ie, no links to the Quick Start or Sample Workflows, etc. Then everything is described in the documentation (Quick Start, etc). Novice users will just go straight to the documentation and see the Quick Start there.

[jcannon-gplates]

And I like the order of your documentation versions. I would just suggest changing indev to development.

• latest stable
• latest development
• 2.0
• 1.3.0
• etc

[jcannon-gplates]

I noticed that the module docstring for oceans.py is nicely detailed but currently doesn't appear in the new Sphinx documentation (AFAIK). I noticed because I just started updating that docstring (for #364).

That docstring appears in the old docs at the top of here. For example, the entire section called SeafloorGrid Methodology.

Just wondering if that module docstring should be moved into a new Primer chapter (mentioned in the above comments) since it details the internal age gridding process (and seems quite useful).

@michaelchin what do you think? I can probably create an issue for this.

[jcannon-gplates]

Actually it probably makes sense to go into class oceans.SeafloorGrid itself (ie, here) since the oceans module docstring does describe some of SeafloorGrid's initialisation parameters.

[michaelchin]

I noticed that the module docstring for oceans.py is nicely detailed but currently doesn't appear in the new Sphinx documentation (AFAIK). I noticed because I just started updating that docstring (for #364).

That docstring appears in the old docs at the top of here. For example, the entire section called SeafloorGrid Methodology.

Just wondering if that module docstring should be moved into a new Primer chapter (mentioned in the above comments) since it details the internal age gridding process (and seems quite useful).

@michaelchin what do you think? I can probably create an issue for this.

The SeafloorGrid Methodology section does not show up in the new doc is because the docstring is at the module(oceans.py) level. The new Sphinx doc was generated from classes. We can move the docstring into class oceans.SeafloorGrid. Or we can move it into the new Primer chapter. I have not strong opinions about either way.

[jcannon-gplates]

One option to add the module docstring somewhere, is to insert this...

.. automodule:: oceans

...which, according to this, only inserts the module docstring by default, so it shouldn't duplicate your existing class documentation.

However, I think only oceans has a detailed docstring though. So, for now, I'll just move it into oceans.SeafloorGrid as part of #364. So we probably don't need a new Primer chapter just yet either.

[michaelchin]

However, I think only oceans has a detailed docstring though. So, for now, I'll just move it into oceans.SeafloorGrid as part of #364. So we probably don't need a new Primer chapter just yet either.

All sound good to me. Thanks John.