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.
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.
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.
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.
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].
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!
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.
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 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.
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 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.
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.
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.
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.
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.
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.
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.
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.
> 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."
> "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.
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.
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.
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.
> 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.
> 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.
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.
> 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.
> 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.
"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.
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.
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.
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.
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 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.
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.
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.
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 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.
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.
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.
> 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.
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.
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).
> 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]
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.
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.
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.
> 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.
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".
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.
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.
> 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 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.
195 comments
[ 3.1 ms ] story [ 162 ms ] threadI never felt in need of an FAQ on their 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.
One more for good measure: the "design principles" page: [3].
[1] https://gds.blog.gov.uk/category/government-as-a-platform/
[2] https://design-system.service.gov.uk/
[3] https://www.gov.uk/guidance/government-design-principles
Introduction
The most common questions we’re asked by visitors to GDS are things like:
This is an attempt to answer those.https://gds.blog.gov.uk/story/
My observation is that in the UK, developer pay in the public vs private sector is not so wildly different than it is in the US.
The public sector can reliably get quite good staff.
They all seem quite fulfilled, too.
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.
This does not have as much overlap with designing a company around being to handle delivery as one might like.
Start at https://www.gov.uk/
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.
[0] https://literacytrust.org.uk/parents-and-families/adult-lite...
https://www.bbc.com/news/business-58670792
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.
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.
25 million people receive the earned income tax credit (i.e. they are poor), and are at high risk of audit https://www.propublica.org/article/irs-now-audits-poor-ameri...
9 million are expats, for whom US tax filing is a special type of hell
15 million are self-employed, which means lots of extra filing https://www.bls.gov/spotlight/2016/self-employment-in-the-un...
putting us at circa 50M out of circa 167M returns filed https://www.irs.gov/newsroom/filing-season-statistics-for-we...
means US tax returns are rather complicated for 30% of people before we start to consider high-income earners.
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'm not sure the average Brit appreciates how good these online services are, on account of never having to use the "average" government website.
> questions take longer to scan and understand than simple headings and you can’t take any meaning from them in a quick glance.
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.
Urbandictionary:
> 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
Good one
Something stable enough that 80%+ of the FAQ will remain relevant 5 or 10 years down the line.
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 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).
> "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?
If these cases are common, they are not edge cases, and they should be described in the actual documentation, guides etc.
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.
That’s the whole point — they don’t have an FAQ page because they put in the work.
FAQ's and its mark-up are about the search experience and not once the user has landed on the site eg for searches like "renew car licence online"
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.
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.
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.
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.
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.
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.
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.
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.
You've identified the problem right here. Writing FAQs avoids solving it.
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.
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.
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.
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.
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.
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.
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.
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.
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 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.
Ultimately, I think documentation should be split up into multiple categories, ala https://documentation.divio.com/
... guys? :(
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.
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.
If you’re talking about TS or Node docs, I’ll agree they’re not on the same level as MDN.
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.
Is not obvious, but can be done from the inside with plain R.
You could also want to type install.packages('ctv') and take a look to Cran task views
Ex. https://clojuredocs.org/clojure.core/reduce
The pattern is definition -> description -> community examples.
If I ever invent a language I am copying this format.
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.
[1] https://documentation.divio.com/
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.
I maintain a FAQ mostly for things over which I have no control,
https://www.reveddit.com/about/faq/
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.
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).
And - more correctly - they should be FGA's:
https://web.archive.org/web/20201231033026/https://jdebp.eu/...
https://web.archive.org/web/20201231033031/https://jdebp.eu/...
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]
[1] https://docs.python.org/3/library/subprocess.html#using-the-...
[2] For example, lists: https://docs.python.org/3/library/stdtypes.html#sequence-typ...
[3] https://doc.rust-lang.org/std/vec/struct.Vec.html
For everything else, you have to consult Popen because it's Popen's API.
Clearly you've never had to do anything in VBA....
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.
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.
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 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.
[0]: https://answersocrates.com/
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 even have a CRT monitor and I still cherish that document.
So what they are saying is that this is a FAQ? :) Is it just that British English calls them "Often Asked Questions"?
Ok, they do them one-per-page on a blog, I've seen them done like that in the past too.
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.
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.
Last month I was browsing my energy supplier's website and was thinking how refreshingly easy their FAQ approach made things:
https://help.so.energy/support/solutions/folders/7000045023
It's not called an FAQ and not every item is couched as a question - but it's basically an FAQ
Ironic?
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.