docs
docs copied to clipboard
openfaas
Troubleshooting page updates or FAQ page
The toubleshooting guide has grown quite large, nearly 500 lines now. That's not a bad thing, but I believe it should be re-organized to make it easier to navigate. It's also a bit difficult to see the different headings on the docs page. Difference between ## and ### are very slight.
Currently, the topics are focused on how to do something:
- Timeouts
- Healthcheck
- Watchdog
These are useful if you know what you're looking for, however, it's difficult to know what you need to do when something is wrong and you're not familiar with the project.
I propose the Troubleshooting guide be updated to a question/answer format to make it easier to find relevant information.
A good example of this is in the "Troubleshooting Swarm or Kubernetes" section: I forgot my gateway password
There have been a couple of conversations happening on Slack that have come up before. The members have linked to sections in the docs, but without knowing what to look for, the others have to ask.
Some examples of questions that came up (in the "openfaas" channel):
- Why doesn't auto-scaling work like I expect it?
- Why is my function not ready after
faas-cli deploy? - How do I invoke a function via cron job?
- How do I change the alert rules?
- I can't access the UI on
localhost
Possibly some of these could go into a new "FAQ" page. Those questions that aren't really problems but more curiosity...
Some more examples of questions that came up in "general" and "contributors" channels:
- How do I use a private container registry?
- How do you pronounce "OpenFaaS"?
- What does it mean for a project to be in the
openfaas-incubator? - I'm want to run tests on OpenFaaS, how should do that?
- Can I run a "micro-service" style function with routes?
- How do I try a function without deploying it?
- How can I forward a function call to another function?
So far most of the proposed questions seem more like FAQ or User Guide/Examples. I am thinking of the docs for the nginx ingress as an example https://kubernetes.github.io/ingress-nginx/examples/
I like the idea of having a FAQ and separating it from Troubleshooting.
Reviewing the current troubleshooting page, it seems like some of those topics really should be References or would be better answered as Tutorials. For example, i think Timeouts coule be moved be a reference and Async Functions and Chaining / Workflows would be better served by tutorials. I also think that the "Healthcheck" section is not named well, I was not expecting that content. It would be better under "I want to report an issue/bug"
I think that the sections on troubleshooting k8s/swarm, CLI unresponsive, and function logs seem to fit well ina "Troubleshooting" section.
I think the two views already stated here have pretty much covered it.
One additional point I would make is around the language used in the FAQ's. We should try to build in sufficient redundant language to make the search function effective. As an example consider the following question:
Q: How do I retrieve my password? A: Exec into the container and run ...etc.
The issue here is that users might perceive this situation is slightly different ways, and so we should pad so that these situations are likely to be caught. E.g:
Q: How do I retrieve my password? A: In situations where you have forgotten, or lost your password and find yourself locked out... Exec into the container and run ...etc.
Initially, this wont be exhaustive but I'd recommend adding consideration in this regard.
@rgee0 i like this idea, make it easier for people find exact phrases that might match their situation, definitely more usable and friendly. I often use Find in Page when I first get to an FAQ to jump around very quickly to the relevant parts