The Human Pages

The Human Pages is a collaborative effort to support researchers and general users of high performancing computing.

Why do we need this?

For many institutions that offer a cluster resource, getting help is sometimes challenging. It might be the case that help comes by way of a user list, a forum, or an enterprise Help Desk software that the institution has invested in. Getting help usually comes down to copy pasting some terminal output into an email, and then having a back and forth conversation with an administrator to diagnose the issue. What are some problems here?

• The user must leave his or her working environment to submit the request. Additional steps might be to open a browser, find an email, and then go back to the terminal to determine important content to send to help debug.
• The administrator very rarely has enough information on the first request to diagnose the issue. The administrator knows little about the environment, software and libraries on the user's path, or even the simple steps the user took to generate the error.
• Requests tend to be redundant. In the best case, an administrator is likely to have a template response for a user logging in the first time,
• Every institution is different, and so it's unlikely that documentation or general resources are shared. Each institution operates somewhat in a silo
• Even with substantial documentation bases, if the bases don't interact with the user from the environment where they are needed, they may not be manually searched and looked at

How can we do better?

It should be the case that each error and ticket helps to grow a knowledge base about high performance computing and programming. When a user asks how to submit a slurm job the first time, the administrator should generate a piece of knowledge about it. When another user asks a second time, he or she should be able to discover the knowledge. Ideally, with simple methods like tags, search, and basic natural language processing, the workload of the administrator is lifted because he doesn't need to write a slight variation of the same help ticket response many times.

What is the content here?

The static content served from this site is programatically generated from the HelpMe collaborative infrastructure, which receives questions from users directly from the command line, organized them for administrators to find and answer, and then a topic or question that represents one or more questions is saved with version control here, and automatically rendered on this site.

How does it work?

Asking for Help

1. We start with a user on a command line. He or she issues a command, and perhaps hits an error message.
2. The user types helpme and writes a brief message about the issue at hand. The user is asked if he/she can reproduce the error, and if so, to do it
3. The error is caotured in its entirety in a video, environment variables and other metadata about the session are also captured
4. The metadata, video capture, and user question are then submit to the helpme portal, and the user receives back immeditely a url to the ticket.

Receiving Help Request

The helpme portal grants accounts to users and adminstrators, and notably, the administrators cross institutional boundaries. A new request shows up as a "post" in a queue, with tags derived automatically from the metadata and video capture. Both administrators and other users can respond with answers and suggestions in a forum style. When an administrator determines a common topic or question is being asked, a topic can be created to add the post to, and a more thorough response written. For this step, and to be deemed an administrator, this means being added as a contributor to this knowledge repo, and what this repository holds are the topics.

Collaborative Development

You can think of a topic as a wiki page, and each topic is a general idea or question with likely many associated posts from users. Each topic is generated in the helpme interface, and updated here. Each change goes to the knowledge repository as a pull request, where it is discussed by the other administrators. When the pull request is approved and merged, the static site is updated here, as is the helpme interface with a webhook.

Extending Knowledge

This simple setup has many advantages.

• The Knowledge Repo is a repository of static text files that can be extended to other applications.
• The helpme command line tool, if used in a Singularity container, can be used on even the oldest architectures.
• Institutions can work together!
• Administrators commonly have preferences for interacting with users. With helpme, an administrator can remain completely in the web interface, interact only with Github, or with Github primarily through emali.

You can find the version history (changelog.yml) in the repository "yaml" file and we add it here for your viewing pleasure.

---

Changelog