Create an FAQ for resolving common issues

[dedemorton]

In issue #675, @ruflin suggested that we create an FAQ in the docs "that contains all the questions which most people will google for first to find an answer. An example here is enabled / disabled or SSL connection to LS not working. The nice part about this is also we can link to it in case someone asks one of these questions on discuss."

@elastic/beats Let's start identifying issues in this thread. Then we can decide what is appropriate for the FAQ.

[ruflin]

• How do I enabled debugging output? Run beatname -c config.yml -e -d "*"
• My connection to Logstash does not work?
  • Check if elasticsearch output is commented out
  • Make sure most recent plugin is installed
  • Link to example config

[dedemorton]

Might be worth putting this in the FAQ (or possibly even having a debugging topic at some point). The FAQ might be a good starting place. Actually, ruflin covers this above. :-)

[dedemorton]

What is the service fails to start? For example: https://discuss.elastic.co/t/windows-packetbeat-service-failed-to-start/29523

[urso]

why is my file not collected by filebeat (hint: ignore_older)

[ruflin]

@dedemorton Probably best we start with 5-6 questions and then we grow it over time. How are FAQ questions normally organised (sorting order)?

[dedemorton]

@ruflin We should definitely reserve the FAQ for common problems (the issues we get asked about over and over again).

The organization of the content depends on the number of questions/answers in the FAQ and how closely related the questions are. If you have an FAQ with more than 8 or 9 issues, then it's good to break it down into categories (performance tuning, troubleshooting, whatever makes sense).

For now, let's brainstorm and come up with a list of possible issues for the FAQ, then we can go through what we have and decide which questions really need to be answered in an FAQ as opposed to just living on the discussion forum.

[markwalkom]

This is something I have been considering doing via a pinned topic in the forums as well.

[monicasarbu]

@dedemorton @ruflin Having FAQ is a great idea. I like it, but I am not sure if the docs are the best place to store those. I would add a FAQ section to discuss (or similar as suggested by @markwalkom) to be closer to where people are asking questions.

[ruflin]

There are some FAQ's already in our docs: https://www.elastic.co/guide/en/elasticsearch/client/curator/current/faq.html I think for google it is interesting to have each topic on a separate page, but I would like to have a least the questions listed on one page.

It is a very good point from @monicasarbu about "where people ask question". I pinned topic that people cannot comment sounds like a great idea. Like this it is also not versioned in the docs and there is only 1 version with the most recent questions.

[dedemorton]

@monicasarbu @ruflin I can see advantages to either approach. I like the idea of having the FAQ in the doc because that's what I have control over (and I'm more likely to maintain it regularly because it's in my face). I can also link to other topics in the documentation and not have to worry about my links becoming stale (when content has moved or a link points to an older version of the doc). One nice aspect of the doc is that it's versioned. We might find that the FAQs vary from version to version. What's true in 1.0 might no longer be true in later versions of the product.

[dedemorton]

@ruflin Incidentally, I like how the FAQ that you pointed to is organized because having the issue in the page title helps with SEO. I'm not sure that a topic in Discuss would be ranked as high.

[ruflin]

@dedemorton I suggest to go with what you prefer most and works best for you. Lets see how it works and then we can start iterating.

[dedemorton]

Another possible item for the FAQ: Why is Redis deprecated? See details about discussion here

[dedemorton]

Another possible item: Why is Filebeat using so much CPU? One reason: value specified for scan_frequency is too low. Example: #781

Note that I'm brainstorming here...we can pick/choose/discuss later.

[dedemorton]

Another possible item: Why is the dashboard in Kibana breaking up my data fields incorrectly? [not the best wording, but I can work on that] The reason: the user has not loaded the index template:

Example: https://discuss.elastic.co/t/packetbeats-dashboard-issue/39724

[dedemorton]

Another possible item: Why is Filebeat keeping old files open? https://discuss.elastic.co/t/filebeat-keeps-open-files-forever/40098

[dedemorton]

another possible item: Why does my SSL client fail to connect? Could list some common configuration issues that lead to this problem, like failing to enable SSL on the logstash side.

[monicasarbu]

@dedemorton I suggest to start an internal document where everyone can add a question to FAQ. What do you think?

[dedemorton]

@monicasarbu Thanks for the suggestion. That's a good idea. It will allow people to edit and comment on the list more easily.

[dedemorton]

Closing this because the initial topics we discussed are now in the doc, but we should continue to add to the FAQ topics as we see users encountering common issues.