Document aspirational documentation structure #293
Conversation
|
Example at 2i2c-org/docs#55 |
docs/structure.md
Outdated
| ## Audiences | ||
|
|
||
| For each feature we add or change we make, we should create & update | ||
| documentation for all of these audiences, as applicable. There are |
There was a problem hiding this comment.
| documentation for all of these audiences, as applicable. There are | |
| documentation for all of these audiences, as applicable. | |
| There are a few key audiences that are outlined below. |
docs/structure.md
Outdated
| People visit our website to learn about us, and investigate if we could | ||
| be of use to them. Communicating what value we can add to them is | ||
| extremely important, so any feature we write should be integrated into | ||
| [our website](https://2i2c.org/infrastructure/). The focus should |
There was a problem hiding this comment.
What is the relationship between this page and 2i2c.org/pilot? In my mind, 2i2c.org/infrastructure is a description of the stack in general but is more like a high-level advertisement, while 2i2c.org/pilot is more dynamic and feature-complete.
There was a problem hiding this comment.
not the infrastructure page in particular, but I really want a page where we can say overall value of what we support, without going into the details - a 'sales' page almost. /pilot is documentation, and much more detailed. So whatever is in the 'sales' page should just be a blurb at most - hence the link to the infrastructure page. A different page is perhaps in order.
docs/structure.md
Outdated
|
|
||
| 1. **Tutorials** for common workflows on our infrastructure, since this is heavily driven by the opinionated choices we have made while building it. | ||
| 3. **How-to guides** to help users accomplish a specific well defined task, especially if it is something they know how to do in a different system. | ||
| 2. **Component reference** to inform users where to find documentation for the component they might be having issues with. Most users are unfamiliar with the intricate details of what component does what, so might not be able to find the appropriate place to look at.j |
There was a problem hiding this comment.
| 2. **Component reference** to inform users where to find documentation for the component they might be having issues with. Most users are unfamiliar with the intricate details of what component does what, so might not be able to find the appropriate place to look at.j | |
| 2. **Component reference** to inform users where to find documentation for the component they might be having issues with. Most users are unfamiliar with the intricate details of what component does what, so might not be able to find the appropriate place to look at. |
docs/structure.md
Outdated
| at least the following kinds of documentation: | ||
|
|
||
| 1. **Tutorials** for common workflows on our infrastructure, since this is heavily driven by the opinionated choices we have made while building it. | ||
| 3. **How-to guides** to help users accomplish a specific well defined task, especially if it is something they know how to do in a different system. |
There was a problem hiding this comment.
I'm curious what you think about content like https://2i2c.org/pilot/admin/interfaces.html - do you think that is in-scope for 2i2c docs? Or something we should instead link to the jupyterhub docs for?
There was a problem hiding this comment.
I've clarified what 'how to' guides should be written, and I've removed the interfaces documentation page in pilot docs. I've moved the content into a 'how to' page instead. So I think we shouldn't have any 'reference' docs (I think of the current page as one) but ok to have howto docs.
docs/structure.md
Outdated
| For each feature we add or change we make, we should create & update | ||
| documentation for all of these audiences, as applicable. There are | ||
|
|
||
| ## For the general public |
There was a problem hiding this comment.
| ## For the general public | |
| ## The general public |
docs/structure.md
Outdated
| 3. **How-to guides** to help users accomplish a specific well defined task, especially if it is something they know how to do in a different system. | ||
| 2. **Component reference** to inform users where to find documentation for the component they might be having issues with. Most users are unfamiliar with the intricate details of what component does what, so might not be able to find the appropriate place to look at.j | ||
|
|
||
| ## For hub administrators |
There was a problem hiding this comment.
Note that we tend to call these people "Community Champions" so far...do you distinguish between the Hub Administrator and the Community Champion?
There was a problem hiding this comment.
We should definitely clearly define it. I think these aren't exactly the same people. For example, with UToronto, Avi / Nathan are who I'd think of as Community Champions. But there's a lot of people who do the day-to-day work, and those are 'admins'. They fulfill different roles, I think. But 'hub administrator' is not defined yet, and we should. Do you have a sense of how we could do that?
There was a problem hiding this comment.
How about we add another role here: https://2i2c.org/team-compass/sre/#roles-needed-to-run-a-2i2c-hub and modify the Community Champion language as needed (if needed)? If you're +1 on that then we can open an issue to track it so it doesn't block this PR
There was a problem hiding this comment.
@choldgraf sounds perfect!
docs/structure.md
Outdated
| Hub administrators are the interface between the 2i2c engineers running | ||
| the hub and the actual users of the hub. They are usually a part of the | ||
| community using the hub, and are interested in the *configuration* of | ||
| the hub infrastructure as well. They shoudl be aware of possible |
There was a problem hiding this comment.
| the hub infrastructure as well. They shoudl be aware of possible | |
| the hub infrastructure as well. They should be aware of possible |
docs/structure.md
Outdated
| involving 2i2c engineers. This will also help surface issues that are | ||
| in need of more automation on 2i2c's side. | ||
|
|
||
| This documentation should exist in the [2i2c-org/pilot-hubs](https://github.com/2i2c-org/pilot-hubs) |
There was a problem hiding this comment.
What about stuff like https://2i2c.org/pilot/admin/interfaces.html - that is for admins, but more on the "hub users" side. Should that be moved to pilot-hubs?
There was a problem hiding this comment.
I think that should definitely continue existing where it is now, since it's targetted at hub admins / users rather than infrastructure engineers
There was a problem hiding this comment.
I made a mistake, this should've referred to the pilot repo. Fixed
docs/structure.md
Outdated
| 2i2c infrastructure. Documentation targetting them should be in this | ||
| repository (2i2c-org/pilot-hubs), regardless of the kind of hub it | ||
| relates to. Since we run our hubs openly, with best practices that can | ||
| ba adopted by anyone, we should try write |
There was a problem hiding this comment.
I think the text here got jumbled
docs/structure.md
Outdated
| 1. **Tutorials**, to help orient folks who might be working on areas | ||
| they aren't already familiar with. | ||
| 2. **How-to guides** for performing common tasks that have not been automated yet. | ||
| 3. |
|
Thanks a lot for the review, @choldgraf! I think big thing left is to define 'hub adminstrators' as different from 'community champions' |
There was a problem hiding this comment.
This LGTM - @GeorgianaElena wanna merge if you like the structure? Otherwise I will merge tomorrow unless you propose changes!
Inspired by https://tljh.jupyter.org/en/latest/contributing/docs.html#how-the-documentation-is-organized