If people are frequently asking the same question then your information and how you deliver it is lacking.
You can solve this by making a FAQ, or your can write better information.
Having recently moved from Python (where the documentation is amazing) to TypeScript/JavaScript (where the documentation is horrendous) this issue has never been clearer to me. The only Python library that I’ve ever had to go outside the documentation to understand has been pandas. I can’t think of a single TypeScript issue I’ve run into that hasn’t ended with me going through an infinite amount of web searching and wading through a gazillion useless suggestions.
It might just be me of course. I never really liked the Microsoft documentation pages either, so maybe I’m just an oddity that can only read Python styled documentation, but maybe not. I mean, why does the Express library have a “security FAQ” which seems like it should basically have been a simple part of the “start here” guide? I’m probably missing something, but reading the security FAQ left me with the feeling you would be an idiot not to use the helmet library with express (at least until you know enough to know when not to use it), and if that is so, then it really shouldn’t be a separate FAQ should it?
I know I went down a side track, but it’s really the most perfect real world example I have of why this article is exactly right.
It's odd but when I have to write something with Python, its documentation really is terrible. There's not even index of functions in particular module, I have to open it, then find that function with ctrl+f. E.g. https://docs.python.org/3/library/os.html
Compare to golang: https://pkg.go.dev/os it provides list of all functions in particular module which I can glance over quickly and find what needed.
That's small thing, but really makes me spend so much more time when I need to use Python for something. I guess that's not an issue for experienced developers who memorized all functions they need.
And I never had issues with JavaScript thanks to wonderful MDN.
I think this is a cultural difference. Python documentation tends to be of the cookbook style, where you have long instructions surrounding specific examples. This works well for some people.
Other language communities (the typical example for me is Haskell) aim more for reference style documentation, emphasising lists of the possible operations and then trusting people to sequence those operations as they wish themselves. That's the type of documentation I like.
I have yet to find a language community that does a good job of both of these styles of documentation at the same time. C# is sometimes in the right direction, but not always.
Neither Python's style nor Haskell's style is sufficient. Howtos ("cookbook" style) and reference information are completely inadequate on their own.
The only acceptable documentation is that which hits all four quadrants of the Divio documentation system[1]: tutorials, how-to guides, reference information, and conceptual explanations. Each of these kinds is necessary in a different situation.
If there's a "cultural" aspect, then it's only in which of the four kinds of docs that those two communities ignore.
That works for one-offs, but becomes a problem when you're working with a set of interrelated features, like a class. There, the very first thing I need is a high-level overview, not a reference. Of course, the reference is still useful for those who are familiar with the thing at hand.
Perl modules often have a long prose introduction, some cookbook examples, followed by a reference style list of all the functions/methods/integration points. Usually pretty comprehensive, although you don't have to have good docs to be on CPAN.
R does a good job imo. Look at the vignette for print in R vs the help page in python. You get your reference style list of possible arguments, you get info on usage as well as additional examples, you even get a See Also section with further reading, and the whole thing has a citation you can reference. The entire language is documented thoroughly like this.
R is a good one indeed. I still haven't figured out how to get a good overview of the functions available in R grouped in some sensible way, but at least once I know which function I want it's often very well documented.
> That's small thing, but really makes me spend so much more time when I need to use Python for something. I guess that's not an issue for experienced developers who memorized all functions they need.
I've been programming in python for almost 15 years and I don't know all the functions/classes/attributes of any module in the standard library probably. What I do know is that if I'm on a vanilla python shell I can type `help(module)` and I'll get that list in the shell directly, and even `help(module.function)` will give me enough context most of the time that I won't need to go online either.
However, as my daily shell, I use IPython, on which I have smart autocomplete that inspects the modules for me by just typing `module.`, hit tab and BAM! All the things inside the module pop up before me to explore. Something looks about what I need? I add a ? at the end an press enter, so `module.function?` will show me the docstring, nicely formatted with the signture (the same thing the built-in `help()` does).
So the online docs, for python, rest on an entirely different level. But sure, coming from other languages it may be weird not having what you're used to. It's part of the languages culture.
The best example of being lost in docs is Python's re (regex). Tons and tons of details upfront when I just want to find examples of basic usage. It should have the examples section with common patterns right at the top. If I have a specific requirement or want the gory details, I can always scroll down.
> Tons and tons of details upfront when I just want to find examples of basic usage. It should have the examples section with common patterns right at the top.
This is called a synopsis, and lack of one is the single biggest mistake that documentation authors make. When I look across the landscape of programming languages, I see them rarely.
Perl documentation always has a synopsis because it's a big cultural expectation, and it almost always useful to get the user started, or to jog the memory. Man pages have it, too, but they tend to cram too much useless information instead of restricting to common cases and patterns.
The issue is that there are conflicting use cases — "I want to refresh myself on how `re` works" and "tell me what order the arguments for `re.match` go in". I think the second use case is most frequent, so an index and some basic examples should go first, but after that a more in-depth synopsis can be very helpful.
I don't think most visits to documentation involve reading the summary; they're either looking for a specific detail (which they can find via the index) or for a common snippet that can be expressed in an example.
If I'm using `re` and I check the documentation 20 times over the course of the week, I'll probably read the summary on my first visit, and then on each of the 19 subsequent visits I'll be looking for granular function details or patterns that I can copy. I think it makes sense to put the most frequently-used stuff at the top. The summary will probably be denser and harder to skim than the examples anyway.
I suppose it really depends though. What you want is to get a bit of everything before the break, so that the user can see a couple intro sentences, a few examples, the index (ideally in a sidebar), and the beginning of the overview before they even have to scroll.
I tend to agree. Python's style of documentation was always hard to parse for me. In comparison I really liked the Ruby core documentation.
Short description with common use case examples followed by a structured list of all implemented functions and a sidebar linking to all relevant interfaces/superclasses. E.g. the Hash class document : https://ruby-doc.org/core-3.0.3/Hash.html
Python's the main language I've used professionally (i.e. used most by a long shot) and I agree. I think it's just a newer style, newer languages and frameworks seem to have a more structured/hierarchical/indexed style like that IME.
Newer? If you look at Javadocs, they're highly structured, at least as much as — and arguably more so than — Go docs.
I think it has got more to do with culture and tradition. Each language seems to have its own documentation culture. Python seems to favor docs in which structure is interleaved with prose.
I find Go docs to be pretty hard to make sense of. Often times they don't explain very well how to use a package. And browsing around different aspects of a library carries a feeling of obscurity.
I agree that python documentation can be clunky especially in comparison with other languages. When I learned python I had experience in bash and R. Man pages and R vignettes have certainly spoiled me. R has usage, details, several examples, even a see also section for further reading. The equivalent python help page for a command like print is a little bit over six lines in comparison.
I like to use Dash https://kapeli.com/dash, which makes browsing the standard library for Python really fast and smooth. One could argue that you shouldn't need a separate app for documentation, and you might be right, but it is a great experience.
Python documentation isn't as nice to read as that of go or rust, and at places a bit hand-wavy. But compared to javascript/typescript it's well structured and thorough. GP just wasn't setting the bar all that high.
Many consider MDN the gold standard when it comes to language documentation and they cover all the JS browser API. I find it much preferable to Python’s docs.
If you’re talking about TS or Node docs, I’ll agree they’re not on the same level as MDN.
> Having recently moved from Python (where the documentation is amazing)
Huh? Python's online documentation is horrible. In addition to what vbezhenar said, there are gems like this:
The arguments shown above are merely the most common ones, described below in Frequently Used Arguments (hence the use of keyword-only notation in the abbreviated signature). The full function signature is largely the same as that of the Popen constructor - most of the arguments to this function are passed through to that interface. (timeout, input, check, and capture_output are not.) [1]
"Largely the same"? What, am I supposed to divine the actually available parameters?
For built-in types, the docs are missing a way to quickly list all available methods and properties. You have to somehow piece it together from various ABCs. [2] Compare this to, e.g., Rust's online doc of its Vec type. [3]
This isn't true.
All sort of people - even the most incentivized to find out a specific information - benefit from a sort of short summary in the form of a FAQ section.
Sure, some can see FAQ as a patch, but I don't see how they can't be a valuable addition even to a well laid out website where information is easily accessible.
The two things aren't mutually exclusive.
Each question comes from a user's comment somewhere, and I often link back to it when answering new questions. I'd be interested to hear if people would prefer a different format or different wording.
Yep, but those are actually Frequently Asked Questions, what I cannot bear is the use of FAQ (and their page) on a brand new site, where there has not been time enough for any "real" question to have been asked by the user.
It is only a (poor) literary form and since they are (mostly) prefabricated, they are either unneeded/duplicated (as the topic is properly explained in the main site/docs) or actually showing that the original text/docs/instructions are not clear enough (and since the Author has control on those, they could be rewritten/amended/corrected to make them more clear).
For me biggest issue are synthetic FAQs because they don't really offer anything that documentation would not. Worst offenders are when CEO tells some intern that they need FAQ on the page so that people can see that other people are asking questions about product ;)
Ideal FAQ lets you search or has questions in a way real person would ask, as those should be written down in a way most people asked such questions. We could even have index of multiple forms of the same question pointing to the right answer.
Problem with documentation is that it is not written there to answer questions. It is written from perspective of "how system works" so someone just writes it down.
For technical documentation like a language I don't expect much need for an FAQ because audience should be able to pose questions and answer those by themselves and then search what is provided like a manual.
For web application or government websites that general audience should use I don't see "documentation" approach viable, you need "Questions and Answers" approach.
Python documentation is not amazing. Search is poor, I expect nowadays instant structured search. Table of contents is generally useless. And important information like common usage is not displayed upfront. Python docs might be great for learning concepts for the first time but not for quickly consulting stuff.
> I can’t think of a single TypeScript issue I’ve run into that hasn’t ended with me going through an infinite amount of web searching and wading through a gazillion useless suggestions
Reading unit tests for me has been my go-to for getting around problems in TS/JS documentation in libraries. Unit tests can sometimes be unintentionally the best documentation. Also helps filter out quickly libraries you'd want to avoid at all costs. No unit tests means you're putting untested code into your system.
The difference between a FAQ and the manual is that typically the manual is comprehensive and organized by topics, while the FAQ is sorted by how frequently people need the information.
If you have a FAQ, then users can scan a dozen questions and see if their question is answered, and in 90% of cases they find the answer.
So the benefit of a FAQ is that you have a single page that contains the most important information across all topics. You don't need to know how the docs are structured, you don't need to know the terms of art to search for, you can just scan a few lines of questions on a single page, which people can do very quickly.
I guess you could put the same information into a document titled "Overview" or "Quick Start" or "Most Important Info" but using the common term "Frequently Asked Questions" makes it easier for customers to know where to start looking.
Completely agree. As a user, I often find FAQ pages to be the single most useful documentation pages.
I rarely read the entirety of the documentation for something, but I usually will read the entire FAQ for something I'm interested in. It has a far higher usefulness-to-length ratio than most documentation, since if done properly, everything in the FAQ was useful to somebody (or hopefully many people).
It's also arguably the best format for certain types of information. For many things, there are "obvious" questions one would ask about them (e.g. "Does this take into account X?", "What about Y?"). When I think of these when reading about something, I'll check the FAQ, and it's often presented right there. It ends up being by far the easiest way to get answers to these types of questions.
FAQs are very useful if they really are FAQs like stackoverflow.
If there is some person "making up" FAQs it is rubbish. When CEO orders that "we need to make FAQ, make one" but no one is actually asking any questions that is the worst.
FAQ should be consisting of actual questions and then best would be each variation of way how people asked it to point to the right answer. Ideally FAQ should be curated by a person or first line support.
Synthetic FAQ is the same as documentation - someone writing things up and organizing it in a way they think. Ideal FAQ should help find question and answer that is already asked by someone else in a way that broadest possible audience would ask it.
Sure, but some of its questions are frequently asked. That’s what the parent was referring to: real questions by real users that sometimes are upvoted by thousands of users.
You can even get a FAQ in a standard format by visiting the “Popular” tab.
UK government online services are, in general, excellent. Easy to follow, clear, reliable. Accessible from almost any hardware, wouldn’t surprise me if my calculator could render it. They put to shame most (all?) commercial sites I can think of.
Agreed. The others here saying FAQs are useful should try gov.uk and understood why they shouldn't be needed. Using gov.uk you really get an idea a lot of research and testing has gone into the text phrasing and structure and the overall look and feel of the site. It's really excellent. I've since seen other countries' government websites copy many of its design aspects - the highest form of flattery. It's all organised by Government Digital Service, who produce "government as a platform" tools [1]. Once you realise that this group have managed to get various IT departments spread across the whole UK government to stick to a common set of tools and design rules, it's clearly an even greater achievement (see their "design system" [2]). All the more so given how large government IT projects normally turn out.
One more for good measure: the "design principles" page: [3].
Government IT projects just work better in the hands of internal teams than external consultancies. It's quite well-known that there's a whole industry of consultancies who make money taking on government contracts with low bids and intentionally expanding the budget by dragging their heels so they can extract the maximum amount of taxpayer money possible. Then the project usually fails and the process repeats.
Even if an external contractor is honest, bidding in the first place requires navigating such a complex process that essentially you're choosing from a set of companies who have designed themselves around being able to handle the bidding process.
This does not have as much overlap with designing a company around being to handle delivery as one might like.
I don't know any developers in the public sector, but friends in various civil service roles love the other perks. Decent pension. Loads of flexidays. One friend could almost work a 4 day week all year.
Really disagree IME — there are great people at GDS, but they're doing it as a vocational thing and could make much more money in private sector.
Generally in the UK you have to go freelancing to earn the top of the market, but even permanent roles in private sector have much better pay for less responsibility. E.g. I saw some GDS "Head of" roles advertised with a salary band ~£60-80k.
AFAIK, they've also dialled back on public sector & they now offer defined contributions nearer to general private sector.
Yep, the divide is still there, I meant it's not quite so extreme. There are good people everywhere, but not having so much FAANG 4x comp vs .gov, maybe the alternative is contracting for 2x perm rate - it does make a difference.
that's also true, in a former life I was a contractor and while I didn't work in the public sector at any point by pure circumstance, a few friends did and they pulled a similar rate to when they were in the private sector.
I tried to do this and found it very easy. I suppose it would be a more stringent test for someone who is ESL and not very tech competent.
I am impressed with the careful and clear use of language to explain everything. It is just so easy to understand what is going on, where I am on the site, and what I need to know.
1 in 6 adults in the UK have poor literacy skills [0] so it's important for the Gov website to clearly give information to people who maybe don't have the best comprehension even in their native language, especially when it comes to government/legal matters.
I think the backstory here is that at some point the government hired the team from theyworkforyou.com (and various other citizen/politics websites), who were clearly very smart and motivated. Wonder if anyone knows more details.
Interesting - it's clear that some talented people on a mission were put in the right place at the right time. I too would be interested to hear from anyone that knows more!
Yes its good once your on the site but not having structured data FAQ's means your not targeting search.
Also looking at FAQ and PAA data does give insight into searches that your not providing information to your users - which you can quickly solve by adding FAQ's
Just blindly assuming that users will automatically know to go direct to the relevant .gov site is typical Civil Service Arrogance.
Don’t know about you, but use this thing called Google, does a really good job of landing me on the correct .gov.uk page almost every time, because the content of those pages is clear and simple enough that you can easily Google what you need.
No duplication, no stupid FAQs that link to thing i actually want. Just one page with the right content at the top of the Google search results.
Agreed. I had to negotiate HM Customs & Excise and pensions pages as a non resident. I tookaway three things
1) they are implementing material design rigidly but sensibly. Consistent style is used to denote active and passive elements.
2) if you comment in feedback to the design they respond. They will even try to respond about non web aspects of negotiating government: it may very coincidental but a year after I fed back we need better international banking paths to pay things british resident people can pay online but expatriates must do as paper cheques (no staples, plain pins may be used to attach cheque to covering letter) they implemented international funds transfer with IBAN.
3) it's plain English. They remorselessly police jargon out.
I was of this opinion until I caught COVID and tried to understand the rules for self isolation. I am quite an edge case in this regard. I found multiple pages saying the same thing with a different ambiguous wording. Some pages even explicitly contradicting each others. It's added a lot of stress to the whole self isolation + sickness situation.
Yeah, the first months were a mess. Contradictory instructions abound, even if you read all of the ordinances, you are still left unsure if you're on the right side of the law (or worse, simultaneously on the correct and wrong side of the law!)
I put that more down to inept guidance given by the government rather than the excellent work of the folks maintaining government websites.
When the government doesn't even follow it's own recommendations and different MPs offer different opinions (and even the PM giving advice that contradicts his own earlier advice!!) it doesn't exactly make the job easy for anyone who needs to document the rules.
Says more about U.K. covid guidelines than GDS. I’m pretty certain our government has created deliberately ambiguous guidance so they can’t get called out for accidentally punishing people if fall into an extreme edge case.
Only something like 15-20% of Brits actually have to do a tax return in the first place. I did mine for the first time this year, and it was surprisingly easy.
Indeed they are. It's a pity that more governments haven't followed their example or that having clear, easy to use government websites is somehow still a too high bar to clear for so many countries.
I'm not sure the average Brit appreciates how good these online services are, on account of never having to use the "average" government website.
For my products, FAQs have always been about edge cases where I usually have no control in fixing/implementing.
For example for Lunar (https://lunar.fyi), an app that controls monitors through the DDC standard:
1. Some monitors may flicker/blackout when Lunar changes brightness
2. The volume can't be changed for specific monitors
3. In a 3-monitor setup, 2 of them change brightness as expected, the other doesn't change at all
All of those issues happen a lot (so they're common) but only for specific setups (so they're edge cases).
I have no control over them, they happen because something in the hardware setup is blocking DDC requests for changing brightness/volume etc. The issue is not detectable, the app gets a successful reply from the monitor, just like everything worked.
This is what I came here to say. I think FAQs for edge cases or very specific questions are very useful.
FAQs can also be a good way to address negative stuff and especially naysayers of a technology or concept - it's difficult to do that directly in content without it getting messy.
For example, a project I'm working on stores data in DNS [0] and some of the feedback we get from technical folks (including HN) is "you can't use other people's infrastructure to do this!" [1]
Addressing this in the spec or content is difficult but having a really clear question of "Is it ok to use other people's infrastructure to serve data?" and having a detailed exploration of that question – far more than you might be able to do in the general content – has real value in my opinion.
Indeed, it is more related to troubleshooting. Which is why Lunar has an automated diagnostics tool which can tell the user if the problem comes from the monitor, and shows some troubleshooting steps specific to their monitor:
And yet, after finishing the diagnostics process, the users still send me emails saying that they paid for the app and I should fix Lunar to support their monitor.
I don't mean that edge cases are frequent, only that they're frequently asked about.
The edge cases happen for less than 2% of my users, but there's a very high chance of receiving a complaint about that edge case.
If I have 10k users and 100 of those encounter an edge case and 50 of those send me emails in the span of a week, I consider that a frequently asked question about an edge case
Given you italicised both common and edge cases I presume you're expecting the following;
You're use of edge cases is non intuitive; If you mean the points in your FAQ are common for the rare setups they effect then perhaps it works. If the effected set ups themselves are common then the issues are not edge cases.
Edge cases by definition are extreme and thus not normal and thus not common.
In my view, there are tens of thousands of ways you can arrange your monitor setup.
Given the factors:
monitor
cable
hub/dock/adapter/dongle
monitor port
maybe KVM
Mac device port
Mac GPU
Mac CPU architecture
monitor firmware
Mac firmware and drivers
There are way too many different types of setups. But most of them work, that’s why I think the ones that don’t work are edge cases.
But I also view them as common because the users that stumble upon those edge cases tend to also complain about them.
They’re not common as in, the app only works for <50% of the users. They’re common as in, I get a ton of email from those 2% of users and I have to respond with the same info every time. So I’d rather have an FAQ where I can direct them to avoid repeating myself.
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.
> 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.
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.
> 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.
> 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.
> 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.
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.
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.
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.
> 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.
"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.
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.
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.
No GDS does both. The run the main portal, but they also consult and build out the actual services as well.
The entire reasons for GDSs success is because they were given the authority to go into and department, and simply replace what they had. GDS designed systems have slowly replaced every other government over the past 10 years.
Today you have to be doing something really unusual to encounter a service that hasn’t been overhauled by GDS. Everything from passport renewals to tax reports have all been rebuilt by GDS, and all are clear and easy to use.
If you’re not a U.K. citizen using gov.uk services, then I have no idea how you can comment on what GDS have and have not built. But it’s substantially more than a portal, the portal is barely scratching the surface of what they’ve achieved.
> If you’re not a U.K. citizen using gov.uk services, then I have no idea how you can comment on what GDS have and have not built.
I am following them and listening them on IT conferences. I didn't know they have such jurisdiction. But obviously, its still not the same thing, far away from it. I am talking about services that take multi years to make and involve 100ths engineers from big companies. Each of them. GDS didn't create a government bank or auction platform or eInvocing system. They can't. Its a "bit more involved" then organizing passports, identification cards, documents etc.
I would argue that developers giving up on simplicity and accepting complexity is almost the reason why teams like the GDS exist. That way of thinking is how things spiral into being so complex everyone hates using the service. It needs someone to reframe the problem as one of "How do we make this simpler?" in order to improve. Until you think about things that way you can't make them better.
You can argue all you want. Giving up on simplicity and accepting complexity seems like a natural thing to do for landing on Moon, no ? No amount of "lets make it simple and just jump really high" will do that.
Lets live in real world, you can't dummy out everything.
The term is wicked problem - it depends on a lot of stakeholders, many of which already in the comfort zone, and you can't change shit without having a major storm.
No amount of "lets make it simple and just jump really high" will do that.
You're confusing "simple" with "easy". Simple things are often extremely hard. The moon landings are a great example - everything about the Apollo lander was as simple as possible. The reason why the inside of the capsule was covered in buttons and switches was that there was pretty much one button for each process. The astronauts followed simple "1 2 3" processes to do each task. The UI could have been a much cleaner, but more complex, set of steps with contextually aware buttons, but that would have made it far more prone to failure. Instead the mission designers decided to use a simpler, safer approach even though that was harder to actually build.
Simple is the opposite of complicated. It is not the opposite of hard.
I get the point they're making but I really like FAQ's. They help with the "know what you don't know" sort of thing at a glance. Perhaps not useful on a gov.uk site, but generally speaking.
I don't understand why people can't simply say "we don't want to do X because of this and that", they have to necessarily say "I don't want to do X, so X is bullshit and nobody else should do it either".
The worst argument ever. Of course it agrees, it is an echo chamber full of terminally online people where you can find any type of opinion unless it was specifically banned by Twitter admins.
> The term for when a person has gotten so deep into social media that they dedicate themselves to issues that have no relevance in their day to day life
I read that last argument as more tongue in cheek than anything else; especially considering the preceding arguments are very well laid out and compelling.
> "What are FAQs?" "FAQs are a way to show you've thought about what your users should know but haven't thought about your users."
Every FAQ I've ever written has been literally a Frequently Asked Question.
If I notice users asking the same question, I add it to the FAQ. I also try to think about how I could make the process simpler so that they don't need to ask that question in the future, but sometimes that's just not possible.
Most of my FAQs are also covered in the manual I provide with my software, but who ever reads a manual?
Unlike a simplified manual, FAQs should cover common edge cases. Things which would look like details and don't clearly fit into the manual's sections.
No its not. I have simplified manual too and a FAQ. Simplified manual shows most important things. FAQ doesn't have to, users can frequently ask totally unimportant things.
I often find that I (and my users) get more value out of a document structured around Frequently Delivered Answers, since it often turns out a bunch of questions end up leading to the same underlying issue.
Generally the answers in question are documented in more than one place already, but no matter how many times one restructures documentation there will still be people who end up with a mistake in their conceptual model that means they're looking in all the wrong places (or if you -do- manage to accrue documentation that covers all of the conceptual models you encounter, often you find you now have a percentage of users who get lost because of how -much- documentation there is, so I've largely resigned myself to there being no such thing as a perfect job there, only incremental improvement as time allows).
I suspect this is much more true of programming projects than it is of the gov.uk websites though.
I was trying to figure out something regarding county zoning by reading a 300-page pdf of county ordinances. Eventually I did a google search and found a FAQ on the county website that had a simple explanation of what I was looking for.
I do understand the argument that a need for a FAQ is symptom of poorly-structured content. But I do think context matters--if it's the federal government providing information about social security benefits, then sure, spend the time and resources to make good content. However, for the case of this small county government with limited resources, the FAQ is a very efficient. I'd rather a small number of my tax dollars be spent on the FAQ than a lot of my tax dollars on rewriting the PDF.
But by the same token, instead of having a FAQ with headings like, "What is the minimum setback for structures?" you could have had a simple document with headings like, "Minimum Setbacks for Structures."
One of the points in the document was that you can still have a document that's structured like a FAQ, just don't make it questions, make it answers.
I think part of the faq benefit is that its designed for people who hone in on faq pages already. Some people are not researchers. They are delegators. They'd rather come to your office and ask you "what is the minimum setback for structures" knowing full well its probably listed somewhere on your website/documents/etc, but they'd rather delegate the effort of looking up that information to you.
A faq page attempts to catch these people, and say "hey delegators, check here if your question has already been answered first before you spam our customer support." In that case, a document that's like a faq but not a faq won't do you any good. These people will just ignore it like the primary document and pound your customer support resources.
Wouldn't a better alternative be a summary of the 300 page document? Both that and a FAQ wouldn't be the canonical sources in a legal capacity, but a summary has the benefit of deduplication and is probably nicer to read (depending on how much you want to cross-reference in the FAQ)
Years ago I wrote the official Rust FAQ [1] (now defunct). The questions were selected based on surveys of Rust users on the major Rust community spaces at the time, and a link to the FAQ was added near the top of the "Documentation" page of the old Rust site. It was also translated into multiple other languages as part of internationalizing the site.
That said, I think it had minimal impact. Often when I would discuss it with others, their response was to be surprised that Rust had a FAQ. There were good answers in there, to questions people genuinely asked frequently, but putting so many useful answers next to each in a single page people were unlikely to discover did not end up being very helpful.
It's a quick fix to redundant support request and therefore a totally valid solution.
If you are in control of your product you can of course try to answer these questions by UI before they arise, but it's a longer route and if you are e.g. a reseller it might not even be possible.
Further some users intents might come up in very diverse situations and you can't clutter all these UI locations with the relevant info for all cases. Once things get more complex, some menus might need nesting and you might also not want to have even more menu entries by duplicating functionality everywhere (that's the MS word solution to this problem I think. You can make text bold in 5 different places at least)
It's totally fine to have an FAQ about "how to make text bold" which will hint you at keyboard shortcuts, the menu bar, the right click, formatting templates etc.
Microsoft Word has one primary button to make things bold, and that's in the Home tab. Since it's such a common tool, it also appears in the cursor toolbar, so make that two.
Of course, you can also use keyboard shortcuts or add it to the user-customizable Quick Access Toolbar, but that applies to anything.
One thing I’ve learned is people consume information in very different ways. Some people read lengthy articles, others want the same information in a sound bite. It’s OK to duplicate information to meet the needs of different audiences.
Further there’s the adage that people don’t hear something unless it’s said to them 5-7 times. I think that applies here. I know from managing people you have to be a broken record. It’s annoying, but it seems to be a truism no matter where you go. You always need to be communicating and overcomminicating.
I instinctively want to agree with you but Apple has persuaded me I'm wrong.
Conventional wisdom has always been that not all users are the same: customisation and different workflows are needed for different people, particularly power users. Yet Apple's philosophy is to work really hard to find what they think is the best way to do something and polish the hell out of it. Power users like us software developers sometimes moan about it, but that doesn't stop us queuing up to buy iPhones!
It makes sense if you are the size of gov.uk, but I agree, FAQs are really useful, and in my experience web editors don't have as many writing blocks when writing lists.
Disagree; rather they're useful for a badly designed site. I can think of several sites I've been to recently where the only way to get to anything was the FAQ.
FAQs are a relic from the old days when websites dealt with obscure topics, provided a lot of value for free with no monetization goal and didn't owe the random visitor anything.
These days it's worth looking into why certain questions are asked "frequently" and if the information can be strutured better in the first place. I also suspect no one is really asking much these days, people just bounce.
> FAQs are a relic from the old days when websites
FAQs are a relic of an older time than that. They date from Usenet groups & mailing lists and similar back when connectivity and storage were expensive and content would expire unless you archived it locally, so you might not know your question has been answered many many times. So FAQ posts appeared and were reposted periodically (even if there were no new updates) so new users would catch them and users that have been away for a while can easily catch up if their have been recent major changes.
They are a bit less relevant for web hosted content, where a frequently asked question implies your content needs an update or a rearrange because the information wasn't easily findable elsewhere.
Also, they have evolved from their original form and are often no longer questions that have been asked on that site but common questions that come up elsewhere, or questions that the author otherwise expects people to ask, at which point the definitely should be worked into other documentation instead IMO. Having said that, a FAQ is easier to put together, can perhaps be done by someone who doesn't have direct write access to the main documentation, and if the information is the sort of thing people should know that you don't want to waste space with to keep other information concise. In this way they can be a useful “background primer” for the relatively uninitiated without padding the main information, but that isn't _really_ a FAQ apart from the name (the name sticks because some people will look for a FAQ before looking for, for instance, a tutorial).
If you get a thousand people asking the same thing on your customer support channels all the time, its worth it to make a faq. even if you had whatever information documented thoroughly, there are a contingent of people who don't care. They'd rather ask for information from someone who would know, a customer support representative or whoever, than look it up themselves somewhere on your website. A faq page specifically targets these people and says "you have questions, skim this first please."
You do know that search engines look for and surface a sites marked up FAQ's - by not having a FAQ your giving up that space possibly to a bad actor in the case of Government sites.
This is assuming that a user makes their way to your webpage at all.
How many questions are asked in natural language on Google or through a smart assistant? Google has standardized the Q&A format for fast answers through their search engine without needing to view the page at all. Without recognizing this use case they are making information more opaque
There's a lot of replies here about how FAQs are useful because users don't bother to read the manual. But...
When was the last time anyone read a manual?
Software these days is so easy to use, and so much effort goes into UX, that most software doesn't need a manual. Games don't have them. Websites don't have them. Web apps don't have them.
The same should be true for other sorts of processes. Things should be simple enough that users can understand them without needing documentation (there will be exceptions, obviously, particularly around safety). If you've put the effort into building something that people can use without reading a manual you shouldn't be getting many questions, and especially not the same questions frequently.
FAQs, like programming languages, are just tools. There are lots of places they're useful, and lots of places they're not well suited.
Trying to convey a main point, or talking about a single topic and informing the reader? Frontloading is going to be more informative.
Lots of disparate pieces of bite-sized information? FAQs display that information quite nicely.
I don't think I've ever personally thought "wow I wish this wasn't an FAQ". They're usually the first things I jump to if they're available. They give me a lot of valuable information very quickly.
Also, the appeal to Twitter is hilarious coming from a government agency.
I agree that information shouldn't be duplicated, but in one of my projects I've taken the opposite approach and made the FAQ the only place that certain information is presented. It's for the library https://github.com/tlocke/pg8000 and I've called them 'Examples' rather than a FAQ, but each time I get a question that isn't covered by the examples I add in a new example. I'd be interested to hear what people think of this approach.
It's a good approach for giving people a point to start/ be inspired by though it will take an increasing amount of time to maintain when your interface changes etc. Reminds me of the aweso.e examples for actix-web that include a lot of common use cases and patterns.
Yes, they're used to populate the People Also Asked snippets. In fact, many SEO types recommend writing all blog articles in an FAQ format. It's why you'll often see a bunch of tangtentially related questions and answer sections in recipes, blog articles, and the like.
The reasoning is that people search for questions so content framed as a Q&A will get picked up for PAA and rank higher generally. Particularly SEO focused bloggers build whole articles by scraping People Also Asked questions for related keywords, dump the questions into a document, and write the answers. Tools like Answer Socrates[0] will do the scraping for you.
Personally, I reckon Google is smart enough to know that "## Cooking Potatoes in the Oven" is likely to provide the same information as "## How Do I Cook Potatoes in the Oven?". And, as the article points out, it's better for readers. I'm not convinced most people search for questions anyway; I'd just type "potatoes oven".
I don’t know, I think this shifts the blame to the user for the sake of some kind of ideological bent. It’s basically saying ‘we know how to document, if you have questions learn how to read.’
Having a FAQ allows for quickly addressing structural issues in information presentation. Creating one ex nihilo is corny, but when the questions actually start rolling in there have a place to be answered while the docs are adjusted.
In my opinion the goal should be to starve the FAQ, not pretend it doesn’t exist.
> We are often asked to put content in Frequently Asked Question format (FAQs). They’re a popular convention on the web, but we don’t recommend them and here’s why:
I am so cheering this on. Whenever I see a FAQ I think, “Lazy, didn’t want to bother organizing the information, doesn’t know how to write documentation.”
FAQs are a microscopic problem, compared to the practice of putting up entirely scripted first level support people who are essentially contractually required to NOT provide any useful explanation or information.
It’s obviously not these individuals fault, but fuck every single institution or company employing this type of idiotic and wholly garbage triage..
FAQs can be used out laziness and and can be a sign that design is lacking, it’s true. But the fact that Stack Overflow exists is testament to the fact that there is a certain class of questions that have answers which depend on ugly reality and hacks around all the leaky abstractions and less-than-optimal things we use every day.
Alternatively, rather than view all Stack Overflow questions as inevitable, we could view Stack Overflow as a failure of the core documentation or system to address user issues sufficiently.
And better documentation should result in fewer SO questions.
In terms of the point of this article I think it is still in-line with what you are saying - as Stack Overflow answers are useful to solve an issue but are much harder to parse/read than properly written documentation on the same topic.
I write internal documentation of our tools or thirdparty tools we use. FAQs are helpful when the topics are very short and/or not linked. They're a stepping stone of getting something documented whilst you find a proper home for it.
I agree with the GDS's view though, especially when its public facing and intended to be read by one of the broadest userbases you can get. When writing a FAQ consider where else you could put that information.
The counterpoint I would use is Amazon's documentation. Each product has an FAQ that rehashes other text in a Q&A format. Personally I love it. Its easy to reach for and its very "no frills". However, the target audience is going to be very different to the GDS. Far more technically literate and likely know what question they want answered.
I totally agree with the blog post, personally, I never read FAQ, but the one argument "The content in our support pages is now appearing in search" is on the other hand the actual reason for some pages having FAQ.
It's an easy way to generate some SEO content.
Honest question: is a FAQ a "curated wiki" where the writers anticipate (or have fielded enough of the same questions) to bring those things they're too annoyed to answer, over and over, to the front?
I think the goal of what you're working on is also important:
- For a marketing page, the content should deliver what the FAQ delivers, which should in principle make the FAQ redundant
- For technical documentation and wikis, there will be too much information to deliver succinctly. But, some content are probably more visited or relevant. Why not pull up the visitor data (or tabulate the list of "where is XYZ questions") into a "Frequently Requested Content"?
FAQs can be useful if they are used as a questionnaire to test our own understanding of the content. But FAQs being the only source of information is pretty terrible and very lazy. Lately, on many Indian government websites, I’ve seen that they straight up just have a list of FAQs and nothing else which infuriates me a lot.
Not the first pretentious nonsense I've seen on that site. Someone there thinks they're some kind of UX messiah and has unfortunately been able to secure a milk crate and a bullhorn
I don't live in the UK, so I can't say how usable their online services are, but I surely love seeing this type of content from them. It's clear people have put some serious thought into UX design.
"If you have frequently asked questions, it's because you haven't answered them in your content."
Errr.... no. You have frequently asked questions because some questions need to be answered frequently. If you have the answers in one place, the user doesn't have to waste as much time searching for it.
Here's some examples of frequently asked questions:
Q: Does God exist?
Q: What is the meaning of life?
Q: How can I be happy?
Q: Why do hot dogs come in packs of 10 but buns come in packs of 8?
I'm sure you could tell users to search the entire web and hope they pull together the right answers. Or you could just do the research, summarize the answer, and provide links, all right next to the question you know lots of people are asking. This will save the users valuable time and ensure they get the correct response.
Here's a point-for-point rebuttal of the article's reasons:
1. "They’re too slow" ... "questions take longer to scan and understand than simple headings and you can’t take any meaning from them in a quick glance."
It doesn't take a genius to scan the list of questions above and find your question. If the question you have is in the FAQ, it is almost always faster to read the list of questions than reading all of the documentation. And the meaning is found in the question combined with which specific category of FAQ it's found in.
2. "They lead to duplication"
Yes. Duplication is the most efficient way to ensure important bits of information make it to the right people. Different people look for and absorb information in different ways. Some skim, some hunt, some meticulously read. Some are in a hurry, some are calm and contemplative. And some people just miss critical information when it's buried somewhere. Duplicated information increases both the likelihood and speed at which the information makes it to the user. Of course, it's a pain to maintain for the content manager, but that's the content managers' job. Don't make the user's life worse to make your job easier.
3. "They’re tonally wrong" ... "The best way to do that, is to write simply and clearly and remove all duplication and superfluous text."
"Twitter agrees" --- proceeds to show one tweet that agrees.
This whole thing is just like saying "you wouldn't need bug fixing if you had no bugs". People ask questions, no matter how good the original content is.
For an official government web site, FAQs have an additional downside - some people will (perhaps maliciously) regard the FAQ answers as the law. Or as official policy. Or similar stunts. This can get you into having lawyers regularly review the FAQs, answers that are half disclaimers, and other messes.
That said, there are many cases where I find FAQs useful. Especially for learning the basic (and oft undocumented) assumptions behind something. Or as a TL;DR alternative to marketing blather, clueless salespeople, and mediocre documentation.
The gov.uk pages are incredibly well written in general, using very careful language to make them both accessible and precise. They’re also well optimised for search, and the answer to almost all my questions is at the top of Google search results.
That’s the whole point — they don’t have an FAQ page because they put in the work.
Well drafted FAQs are rarely "frequently asked" but they have become a conventional way of conveying extra information. We're all in the habit of checking FAQs if we need more info. Why re-invent the wheel?
A mix-and-match style can work well
Employed judiciously, FAQs can help promote clear drafting by moving points of complexity out of the main body of text. A post-script list of questions is more intuitive than a disconnected list of additional headers. For example, public facing docs need to work for readers with different levels of literacy. FAQs at the bottom of a document are a lightweight way to add additional nuance for those who want to dig a bit deeper.
What does user testing say?
Not clear from the UK.gov blog post. Gives the impression that this is just one person's position. It wouldn't be the first time that UK Government takes a belligerent approach ;) It would be more convincing if the argument was backed with research. Citing a dude on Twitter doesn't cut it.
You can solve this by making a FAQ, or your can write better information.
Having recently moved from Python (where the documentation is amazing) to TypeScript/JavaScript (where the documentation is horrendous) this issue has never been clearer to me. The only Python library that I’ve ever had to go outside the documentation to understand has been pandas. I can’t think of a single TypeScript issue I’ve run into that hasn’t ended with me going through an infinite amount of web searching and wading through a gazillion useless suggestions.
It might just be me of course. I never really liked the Microsoft documentation pages either, so maybe I’m just an oddity that can only read Python styled documentation, but maybe not. I mean, why does the Express library have a “security FAQ” which seems like it should basically have been a simple part of the “start here” guide? I’m probably missing something, but reading the security FAQ left me with the feeling you would be an idiot not to use the helmet library with express (at least until you know enough to know when not to use it), and if that is so, then it really shouldn’t be a separate FAQ should it?
I know I went down a side track, but it’s really the most perfect real world example I have of why this article is exactly right.