Create a FAQ and "common user problems" section in our documentation

choldgraf commented 2 years ago

Background and proposal

There are some cases where users will run into common issues in the hub. These might not be fixable in the long-term, and will need some kind of user action each time it is encountered.

Instead of having a one-on-one support conversation every time, we could try to document the more common of these for others to reference.

Examples of this issue:

Websockets browser issue - in this discourse post the user reported some strange behavior where the UI seemed to work but was unresponsive. We decided this was likely a websockets issue, and there might be some specific things to try in order to fix it.
Random .nsf*** files being generated* - in this support ticket we had a report that random `.nsffiles were being created. It seems this is because of [some weird NFS behavior](https://www.ibm.com/support/pages/what-are-nfs-files-accumulate-and-why-cant-they-be-deleted-even-after-stopping-cognos-8) and the short-term fix was to add.nfs*to the.gitignore` file.

In both cases, it didn't seem like a fix could be applied at the cloud infrastructure level, so some docs could have helped guide the person forward.

Implementation guide and constraints

I think there are three potential ways of documenting this kind of thing:

**A dedicated "Common problems" or a "Troubleshooting tips" section as a top-level section in the user docs.
Dedicated subsections under each topic for this kind of thing (e.g. a section under "Authentication" could be called "Common problems").
Using a different space for more free-form Q&A style content. For example, Discourse forums often serve this purpose, so that users can search through forum results for similar questions.

Updates and ongoing work

No response

damianavila commented 2 years ago

I would start with step 1 and see if that works/helps. I am worried that if we start a Discourse right now, we will not have the resources to keep an eye on it...

jmunroe commented 2 years ago

[ ] https://github.com/2i2c-org/docs/issues/168

2i2c-org / docs