-
Notifications
You must be signed in to change notification settings - Fork 4
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
Documentation Jumping Off #25
Comments
Thanks so much for sharing Rachel. This is incredibly useful. |
Agreed! This is awesome, Rachel. 🤩
Merging changes to the As a first step, could you open a PR to In case it wasn't apparent (it took me a while to figure this out myself!), a PR to add that page should:
If you are working from a local branch that hasn't merged changes from 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. |
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
Should I instead be forking the repo and creating a new branch there, as this stackoverflow suggests? |
Exactly! You should be able to re-use your existing changes by following these steps:
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. |
@rwegener2, one additional thought, picking up from my earlier comment
... 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 Again, let me know if further clarification would be helpful! |
Thanks @cisaacstern that was very thorough! A PR is here. |
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. |
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:
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:
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.
The text was updated successfully, but these errors were encountered: