Documentation Jumping Off

[rwegener2]

Goal

The goal of this ticket is to share some ideas for the architecture of the Pangeo Forge documentation.

First goal: Central Docs Page

As I was navigating Pangeo Forge in May the biggest difficulty for me was that there was no central jumping off point for understanding Pangeo Forge. I think one primary goal for the documentation should be to develop a place like that. https://pangeo-forge.org/ seems like a logical place for that, but the where is less important

Developing the Central Docs Page

I really liked the Divio resource that @cisaacstern linked in an earlier conversation segmenting documentation into four separate purposes and formats.

Using the Divio concept of documentation as a guide, the role of the central jumping off point would be:

1. Provide a description of how the Pangeo Forge documentation is organized
2. Explanation type documentation (and maybe Tutorials or Howto) about the entirety of the Pangeo Forge ecosystem. This is documentation that wouldn't fit into one specific repository because it would explain how the components of Pangeo Forge (bakeries, feedstocks, recipes) fit together
3. Provide links to the varies repos that make up Pangeo Forge and to API reference pages of those repos

This gist comment has an example of what a jumping off page could look like. I didn't push the branch I have because I don't actually have permissions to write to the pangeo-forge-vue-website repo, but if that would be helpful I imagine we can get that sorted out.

Other Assorted Thoughts

Mid-Level Technical Description

One thing that was also challenging about learning Pangeo Forge was that it felt like there was a leap from very high level description to very low level description. There was a roadmap, which provided a really nice broad vision of why Pangeo Forge exists, and then there was the tutorials for the pangeo-forge-recipes repo https://pangeo-forge.readthedocs.io/en/latest/ which described how to do very specific tasks. I typed this text up as I was learning to create a mid-level technical description of Pangeo Forge. It isn't complete because there were still things that I didn't understand about the way Pangeo Forge works, but again hopefully it's a starting point and illustrates the idea. A description like this could be a link from the central docs page.

Standard section of repo readmes

Because there are so many repositories one idea I had was to try to get all Pangeo Forge repositories to start with a similarly structured piece of intro text that would describe how that repository connects to the others and also provides a link back to the central documentation page. What I started typing up is here.

Central diagram

I like that a core image to describe the Pangeo Forge process is being developed ("How it works" section of the website homepage). The current image was difficult for me to understand, I think because of the mixed level of description depth (ex. "github actions" arrow is specific but other arrows aren't, or there is a lot of info about bakeries but feedstocks aren't mentioned). I spent some time trying to come up with an image that equalized the amount of information describing all three of the core Pangeo Forge components. I'm not really convinced this diagram is currently well developed enough to be used but if folks like it I would be happy to update it and integrate feedback to get it to a point where it could be a broadly used diagram.

User groups

One other thing I did consider was the various user groups that would be engaging with Pangeo Forge. I can see:

1. Recipe contributors
2. Bakery maintainers
3. Pangeo Forge infrastructure contributors

In the short term it sounds like the vast majority of the focus is on group 1. I still added this list to as a small reminder that we might consider how the documentation architecture that is set up now could support the 2nd and 3rd user groups as the project expands.

Wrapping Up

This smattering of ideas is what I have typed up. I know a lot of these ideas are only half baked but I'd be happy to jump in for discussion or some chunks of work if it would help get them over the finish line.

[rabernat]

Thanks so much for sharing Rachel. This is incredibly useful.

[cisaacstern]

This is incredibly useful.

Agreed! This is awesome, Rachel. 🤩

I didn't push the branch I have because I don't actually have permissions to write to the pangeo-forge-vue-website repo

Merging changes to the main branch of pangeo-forge-vue-website triggers Netlify to rebuild the live site, so for the simplicity at the moment, I do think it makes sense for us to have fewer people doing that. But that shouldn't prevent anyone from opening PRs against pangeo-forge-vue-website.

As a first step, could you open a PR to pangeo-forge-vue-website including the Documentation page you've rendered in your gist here?

In case it wasn't apparent (it took me a while to figure this out myself!), a PR to add that page should:

1. Add the page itself as a file called Documention.vue to src/components/
2. Add a reference to it in src/router/index.js
3. Change the Documentation href in src/App.vue

If you are working from a local branch that hasn't merged changes from pangeo-forge/pangeo-forge-vue-website in the last 24 hrs or so, you'll need to do that as well, as I pulled a PR into main yesterday morning.

I am truly thrilled to be collaborating with you on this, Rachel. Your insights are spot-on and the entire Pangeo Forge community will benefit immensely from them. Please let me know if any of the above is unclear or if you hit any roadblocks with it, and I'll be happy to help.

[rwegener2]

Thanks @cisaacstern, that explanation was super clear and I'm really glad that the feedback is helpful!

With respect to pushing my branch: I cloned the repo, made my changes to a branch and attempted to push it. When I do git push origin docs-example I get an error:

remote: Permission to pangeo-forge/pangeo-forge-vue-website.git denied to rwegener2. fatal: unable to access 'https://github.com/pangeo-forge/pangeo-forge-vue-website.git/': The requested URL returned error: 403

Should I instead be forking the repo and creating a new branch there, as this stackoverflow suggests?

[cisaacstern]

Should I instead be forking the repo and creating a new branch there

Exactly! You should be able to re-use your existing changes by following these steps:

1. On GitHub, fork pangeo-forge-vue-website so that you have a copy of the repo at https://github.com/rwegener2/pangeo-forge-vue-website.git
2. From a Terminal window, navigate to your existing docs-example branch, and add your new fork as a git remote:

   git remote add rachel https://github.com/rwegener2/pangeo-forge-vue-website.git

3. Confirm that you've added your fork as a new remote with git remote -v, which should now return something like:

   rachel  https://github.com/rwegener2/pangeo-forge-vue-website.git (fetch)
   rachel  https://github.com/rwegener2/pangeo-forge-vue-website.git (push)
   origin  https://github.com/pangeo-forge/pangeo-forge-vue-website.git (fetch)
   origin  https://github.com/pangeo-forge/pangeo-forge-vue-website.git (push)

4. Push your docs-example branch to your fork with:

   git push rachel docs-example

5. Go to https://github.com/rwegener2/pangeo-forge-vue-website.git and click Compare and pull request to open a PR against origin

Let me know how it goes and if any further clarification would be helpful! Really excited to see the PR and get your suggestions incorporated into the website ASAP 😄 . Thanks for all your effort on this, Rachel.

[cisaacstern]

@rwegener2, one additional thought, picking up from my earlier comment

If you are working from a local branch that hasn't merged changes from pangeo-forge/pangeo-forge-vue-website, you'll need to do that as well

... in case it's useful, here's a few steps for that (numbered so they fit between steps 3 and 4 above):

3.1. Before pushing your branch to GitHub, run git fetch origin to fetch any recent changes from https://github.com/pangeo-forge/pangeo-forge-vue-website.git 3.2. On your docs-example branch, run git merge origin/main to incorporate any changes in the main branch of the website which are not already part of docs-example 3.3. If docs-example changes any lines that are also changed by the incoming merge, they will need to be resolved. VS Code provides a relatively simple UI for that, which looks like this.

Again, let me know if further clarification would be helpful!

[rwegener2]

Thanks @cisaacstern that was very thorough! A PR is here.

[cisaacstern]

Awesome, @rwegener2! Discussing these suggestions is an item on the agenda for today's Pangeo Forge Coordination meeting, taking place in ~15 minutes at 2pm ET on https://whereby.com/pangeo. It would be great if you can make it, but if not no worries at all. Either way, I'll review the PR within the next day or so.