4 ms·

FAQ is valuable. You cant mistake FAQ for bad or incomplete documentation. Its just one focused document on particular aspects of the entire system. People ask

FAQ is valuable. You cant mistake FAQ for bad or incomplete documentation. Its just one focused document on particular aspects of the entire system. People ask about the same or similar things, its a known phenomena. People don't RTFM and manual may be overwhelming. You get value in reading the most frequent questions as a user too, and although all the facts can be deducible from the manual, they are here on one place now, isolated from the rest of the docs. Compare this to quick/short introduction most manuals have and you get the same duplication problems and the same beneficial points. In conclusion, FAQ is legit.

mankyd 5y ago
Agreed. Honestly, I often jump to a faq early in my research when I'm thinking to myself: "just give me the highlights." It's context dependent though. If it's a one page, cliff notes style faq, great. If it's a large, searchable, knowledge base, then that's just documentation masquerading as a faq - often poorly so.
- Veen 5y ago
  > I'm thinking to myself: "just give me the highlights." That's the problem though. The "highlights" should be front-and-center in the main content. If it isn't then the content is poorly designed, and the FAQ is just a way of working around bad content without fixing it.
atoav 5y ago
> People don't RTFM and manual may be overwhelming. I think the point they are getting at here, is that if you write your information in the right way, people won't need a FAQ. As devs we all know the difference. There is documentation that is just a good read – not in the sense of "simple to read", but in the sense of "this is something I actually enjoy reading". If this is the case and all questions are answered, you won't need a FAQ. Granted – there will still be people who will go like "LOL didn't read" – but what makes you think these will read a FAQ? If we follow their line of thinking, you should have a "Occasionally asked Questions" section for all the questions that sometimes could arise in certain readers, but arise to rarely to put it into the actual text.
- majkinetor 5y ago
  > if you write your information in the right way, people won't need a FAQ Such thing doesn't exist. You are ignoring the complexity of human beings. There is no one solution fits all. I for instance don't like narrative docs, but factual, math like. Most people don't.
  - notriddle 5y ago
    By definition, an FAQ covers the common cases, not the full complexity of human beings. The long tail of edge cases need a full reference manual, not an FAQ.
    - majkinetor 5y ago
      FAQ covers 1 use case. It doesn't cover complexity. The entire docs is for that.
- LudwigNagasena 5y ago
  But how can you write the information in the right way for everyone? I can imagine dozens of different customer journey maps for the gov.uk website. It seems useful to maybe duplicate some information here and there to make different customer journeys more straightforward.
  - avianlyric 5y ago
    > It seems useful to maybe duplicate some information here and there to make different customer journeys more straightforward. Strongly disagree with this. It’s something the Neatherlands government does. Trying to understand their COVID rules for traveler's was hell, because they duplicated the same information for different flows. This created two problems: 1. Google turned up half a dozen similar, but different pages with the same content. 2. It was impossible to figure out what the canonical version of the information was, when each page was subtly different. 3. Each version assumed you already had some context, but didn’t tell you where to find that context. So you were left with stupid statements like “You must fill out a travellers form” but no link to the form, and search will bring up half a dozen results, all subtly different again. Contrast that to gov.uk, where there were a number of high level articles that stepped you through the decision process, with links (gosh, using hypertext to link to useful information, what in idea) to pages that had all the details and context for each specific step, if the summary on the page wasn’t enough. Those pages then contained all the detail and context you needed to understand the nuance of the issue, and linked to other similar pages if you needed more context. The result was that I was able to understand the travel rules for the U.K. without every leaving the gov.uk site and using Google, because all the information was properly linked together, and first page I landed on from Google was either the right starting point, or had a big button at the top which took me to the right starting point.
onion2k 5y ago
manual may be overwhelming You've identified the problem right here. Writing FAQs avoids solving it.
- majkinetor 5y ago
  "Overwhelming manual" is not objective thing. Some domains need to have overwhelming documentation because they are so complex. Even with careful design of such docs (i.e. progressive disclosure, cross linking etc.) it still can be overwhelming and it depends on your background. It also ignores the context - I create gov services, and people are mandated to use them by the law, not because they want to. No amount of design will solve that. They come to spend as low amount of time as possible in order not to have legal repercussions.
  - onion2k 5y ago
    I create gov services, and people are mandated to use them by the law, not because they want to. No amount of design will solve that. The article that this thread is about is written by someone on the UK government digital service team. The UK government puts significant effort into doing exactly what you say isn't possible. The GDS team solve those exact problems by designing services that users can easily use without FAQs (or even looking at the documentation in most cases). And, as a British person in the UK who uses the government's websites a bit, I have to say they do a really good job of it. If you believe designing government services means you can't design them well and make them easy to use then I suggest you invest time reading the GDS blog. You will learn a lot.
    - majkinetor 5y ago
      The GDS team works on portal to other services. I design services which are way more complex. Think of stuff like budget execution or online banking. Not the same problem. > And, as a British person in the UK who uses the government's websites a bit, I have to say they do a really good job of it. I agree. When I was working on similar website for our government, I used UK.gov as a reference. > If you believe designing government services means you can't design them well and make them easy to use then I suggest you invest time reading the GDS blog. You will learn a lot. I didn't say that. My services are very easy to use, but still have massive documentation. And no, I learned from GDS 10 years ago. They can probably learn from me now. I have way more experience and countless public services with total of around 100M users on all of them.
Too 5y ago
I think this view comes from someone answering questions, not from someone asking them. In that context they can still be useful. Sort of like a canned response you get from first line support. The better thing would be if the question didn’t need asking in the first place. If your manual is overwhelming, that’s a problem with the manual.
- majkinetor 5y ago
  Nah, world is more complex then that. Any shit like this, claiming it knows how to simplify complex human behavior is meaningless. Both article, and bunch of comments here are useless simplification of real life. While you should make things simple, you should not make them simpler then possible because then they are just wrong.

mankyd 5y ago

Agreed. Honestly, I often jump to a faq early in my research when I'm thinking to myself: "just give me the highlights." It's context dependent though. If it's a one page, cliff notes style faq, great. If it's a large, searchable, knowledge base, then that's just documentation masquerading as a faq - often poorly so.

Veen 5y ago
> I'm thinking to myself: "just give me the highlights." That's the problem though. The "highlights" should be front-and-center in the main content. If it isn't then the content is poorly designed, and the FAQ is just a way of working around bad content without fixing it.

atoav 5y ago

> People don't RTFM and manual may be overwhelming. I think the point they are getting at here, is that if you write your information in the right way, people won't need a FAQ. As devs we all know the difference. There is documentation that is just a good read – not in the sense of "simple to read", but in the sense of "this is something I actually enjoy reading". If this is the case and all questions are answered, you won't need a FAQ. Granted – there will still be people who will go like "LOL didn't read" – but what makes you think these will read a FAQ? If we follow their line of thinking, you should have a "Occasionally asked Questions" section for all the questions that sometimes could arise in certain readers, but arise to rarely to put it into the actual text.

majkinetor 5y ago
> if you write your information in the right way, people won't need a FAQ Such thing doesn't exist. You are ignoring the complexity of human beings. There is no one solution fits all. I for instance don't like narrative docs, but factual, math like. Most people don't.
- notriddle 5y ago
  By definition, an FAQ covers the common cases, not the full complexity of human beings. The long tail of edge cases need a full reference manual, not an FAQ.
  - majkinetor 5y ago
    FAQ covers 1 use case. It doesn't cover complexity. The entire docs is for that.
LudwigNagasena 5y ago
But how can you write the information in the right way for everyone? I can imagine dozens of different customer journey maps for the gov.uk website. It seems useful to maybe duplicate some information here and there to make different customer journeys more straightforward.
- avianlyric 5y ago
  > It seems useful to maybe duplicate some information here and there to make different customer journeys more straightforward. Strongly disagree with this. It’s something the Neatherlands government does. Trying to understand their COVID rules for traveler's was hell, because they duplicated the same information for different flows. This created two problems: 1. Google turned up half a dozen similar, but different pages with the same content. 2. It was impossible to figure out what the canonical version of the information was, when each page was subtly different. 3. Each version assumed you already had some context, but didn’t tell you where to find that context. So you were left with stupid statements like “You must fill out a travellers form” but no link to the form, and search will bring up half a dozen results, all subtly different again. Contrast that to gov.uk, where there were a number of high level articles that stepped you through the decision process, with links (gosh, using hypertext to link to useful information, what in idea) to pages that had all the details and context for each specific step, if the summary on the page wasn’t enough. Those pages then contained all the detail and context you needed to understand the nuance of the issue, and linked to other similar pages if you needed more context. The result was that I was able to understand the travel rules for the U.K. without every leaving the gov.uk site and using Google, because all the information was properly linked together, and first page I landed on from Google was either the right starting point, or had a big button at the top which took me to the right starting point.

onion2k 5y ago

manual may be overwhelming You've identified the problem right here. Writing FAQs avoids solving it.

majkinetor 5y ago
"Overwhelming manual" is not objective thing. Some domains need to have overwhelming documentation because they are so complex. Even with careful design of such docs (i.e. progressive disclosure, cross linking etc.) it still can be overwhelming and it depends on your background. It also ignores the context - I create gov services, and people are mandated to use them by the law, not because they want to. No amount of design will solve that. They come to spend as low amount of time as possible in order not to have legal repercussions.
- onion2k 5y ago
  I create gov services, and people are mandated to use them by the law, not because they want to. No amount of design will solve that. The article that this thread is about is written by someone on the UK government digital service team. The UK government puts significant effort into doing exactly what you say isn't possible. The GDS team solve those exact problems by designing services that users can easily use without FAQs (or even looking at the documentation in most cases). And, as a British person in the UK who uses the government's websites a bit, I have to say they do a really good job of it. If you believe designing government services means you can't design them well and make them easy to use then I suggest you invest time reading the GDS blog. You will learn a lot.
  - majkinetor 5y ago
    The GDS team works on portal to other services. I design services which are way more complex. Think of stuff like budget execution or online banking. Not the same problem. > And, as a British person in the UK who uses the government's websites a bit, I have to say they do a really good job of it. I agree. When I was working on similar website for our government, I used UK.gov as a reference. > If you believe designing government services means you can't design them well and make them easy to use then I suggest you invest time reading the GDS blog. You will learn a lot. I didn't say that. My services are very easy to use, but still have massive documentation. And no, I learned from GDS 10 years ago. They can probably learn from me now. I have way more experience and countless public services with total of around 100M users on all of them.

Too 5y ago

I think this view comes from someone answering questions, not from someone asking them. In that context they can still be useful. Sort of like a canned response you get from first line support. The better thing would be if the question didn’t need asking in the first place. If your manual is overwhelming, that’s a problem with the manual.

majkinetor 5y ago
Nah, world is more complex then that. Any shit like this, claiming it knows how to simplify complex human behavior is meaningless. Both article, and bunch of comments here are useless simplification of real life. While you should make things simple, you should not make them simpler then possible because then they are just wrong.