Hey friends! I'll add some notes here to follow up on the docs discussion we had earlier (I know you guys are at lunch, no worries!) I think we would do very well to do the following:
Github is really a strong base for current and future development. It will support integration with just about anything, involve users, and have version control and immedate rendering to nice webby places. So it follows that you can think of a documentation base as a Github repo.
Imagine some theoretical stanford-rc/lessons repo where we start adding content.
We can first make a very generic listing of "things people would want help with. I'd be happy to take resources from the
previous step, and organize things for a first shot. E.g."
- What is reproducibility? --> version control --> Github
- What is a research cluster--> slurm --> running jobs
The organization of the Github repo isn't really that important, but will reflect an organization of questions that users typically hit. In doesn't actually matter a ton in the long run because we can render it however we like. Here is a dummy example for the post above:
version-control/
github/
README.md
example1.md ...So the user might browse to https://stanford-rc.github.io/lessons (or whatever the repo is called) to find these rendered markdowns. And what else is included within them? Asciinemas! And not just asciinemas, actual videos of us teaching. I figured out how to do this, and you have supreme control over windows / integrations / etc. Here is a dummy example with two windows
https://www.youtube.com/watch?v=FPjkkjXa910&feature=youtu.b
This would mean we would have a youtube presence for our group, and different series of lessons to watch. The lessons would be linked from the docs, which means we get YouTube also exposing our help, and users that like watching videos can just forget about the writing bits entirely and have Github do it's magic to direct to the next video. Do you see where I'm going with this? if it's a liked thing by users, this transitions very nicely into more of a structured course / lesson sort of deal. You should be able to easily find the "Stanford SRCC onboarding" videos. We might be able to show the value in having it and then convince stanford that new graduate students should have some kind of more official "HPC" onboarding that could be a proper lesson in Udacity, etc.
Where does HelpMe fit in? Because these docs will be served on Github, this means two things. The first is that it's very natural for a user to find a documentation, have a question, and then create an issue asking for an answer. A user might also think the doc is incomplete and submit a pull request for a change. It also means integration with tools like HelpMe via access a la API. You can use the Github API to search content, so theoretically a user could do this:
helpme search How do I submit a slurm job
and then the "search" endpoint is configured on the cluster to use any number of repos, and return the result to the user (in some format, link or actual text content, depending on how it's implemented)
You can submit a slurm job with...
sbatch...
or look man sbatch to get more help.
I can set up an easy way to do this, it involves just formatting in the help markdown file.
On a high level, submitting a HelpMe request would basically search some docs endpoint (Doesn't have to be Github) and we return them a response that has some content (a link video / entire asciinema to play, whatever) to help out. It's a very general thing - any kind of search can be done for any endpoint that is integrated as a plugin. The "search" function could be configured to hit different endpoints (e.g., a search of some githug repos and of a wikipedia page). This is why helpme is cool! :) If other research computing groups also make repos, then adding them to the search is trivial.
I'm happy to get us started on this, I'm thinking this is how I'd proceed:
- start with already existing sources of user (and SRCC) docs.
- (our group) create a list of things users commonly need help with (from your experience). Add to that additional issues/topics that are important
- create a
stanford-rc/lessonsrepository to organize - start writing up friendly walk throughts for them. Each document should be focused around one tiny idea, doing one thing. It would coincide with a thing that the user would actually want to do.
- while the above is going on, create the template that it renders to
- for each tiny thing, create asscicated asciinema / short video / example scripts.
Then after the above, be annoying and loud and post it places! Then integrate into HelpMe and show people how to use it. The user should then be able to:
- search google nad find the specific question they want
- read the example / watch the asciinema or video / post a question to the linked issue board for it
- for more complicated stuffs, clone the repo to get the script (or jupyter notebook, etc.)