4 ms·
> 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
by 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 agoBy 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 agoFAQ covers 1 use case. It doesn't cover complexity. The entire docs is for that.
- LudwigNagasena 5y agoBut 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.
- atoav 5y ago> But how can you write the information in the right way for everyone? The same way you create any media that works for everyone – those writing have to be well aware of the way their diverse target audience will perceive the text and distribute escape hatches for everyone. This can feel at times like balancing an equation with many variables, but key here is, that the writer believes that there is a solution that works for most people at the same time. Example: You can write a introduction to a hard technical topic, that has a joking tone and is entertaining to advanced users, while to not so advanced users it explains the core concepts of what they need to know in order to understand the rest of the text. This way you wrote a single text, that means something different to two groups of people (and both times in a positive way). So the goal of a good writer is to find that one text which reads well from multiple perspectives. Of course you cannot cover all perspectives, but thinking about which perspectives to cover already is much better than just writing down your stream of consciousness.