[HN Gopher] FAQs: Why we don't have them (2013)
___________________________________________________________________
FAQs: Why we don't have them (2013)
Author : open-source-ux
Score : 224 points
Date : 2021-12-07 07:51 UTC (15 hours ago)
(HTM) web link (gds.blog.gov.uk)
(TXT) w3m dump (gds.blog.gov.uk)
| bananamerica wrote:
| I find FAQs are often useful and even interesting.
| 0xbadcafebee wrote:
| _" 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."_
|
| Oh, piss off. Duplication is fine, see point 2.
|
| 4. _" Twitter agrees"_
|
| Oh, piss off! See point 3.
| alin23 wrote:
| 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.
|
| Best I can do, is a lengthy FAQ:
| https://lunar.fyi/faq#brightness-not-changing
| LordAtlas wrote:
| > For my products, FAQs have always been about edge cases where
| I usually have no control in fixing/implementing.
|
| If they're edge cases, they don't fit the "F" in "FAQ".
| mst wrote:
| The half dozen most encountered edge cases in any given
| system will often generate the vast majority of the support
| requests.
|
| Or: The F in FAQ is about the Frequency amongst Questions
| that are actually Asked.
| alin23 wrote:
| 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_
| iechoz6H wrote:
| 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.
| alin23 wrote:
| It's a bit confusing, I know.
|
| 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.
| elliottinvent wrote:
| 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.
|
| 0. https://www.num.uk
|
| 1. https://news.ycombinator.com/item?id=27632195
| pornel wrote:
| That sounds like a troubleshooting section.
| alin23 wrote:
| 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:
|
| https://files.lunar.fyi/lunar-diagnostics-demo.mp4
|
| 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.
| crtechmbd wrote:
| I am experimenting with the idea that FAQs can be crowdsourced so
| the best FAQs bubble to the top. Looking for feedback on how to
| make the product usable
| https://chrome.google.com/webstore/detail/anywyse/gfohefaikk...
| atlasV wrote:
| these random decisions makes GDS extremely unviable ..
| rich_sasha wrote:
| 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 never felt in need of an FAQ on their websites.
| ggm wrote:
| 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.
| toto444 wrote:
| 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.
| steerablesafe wrote:
| I know you are replying about "gov.uk" being clear or not,
| but I would just like to add that a FAQ would probably not
| cover an edge case.
| hnlmorg wrote:
| 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.
| avianlyric wrote:
| 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.
| nicoburns wrote:
| To be fair to the GDS team, I think it's the policy itself
| rather than the presentation of it that's confusing and self-
| contradictory in this case.
| zinekeller wrote:
| 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!)
| ssl232 wrote:
| 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].
|
| [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
| beaconstudios wrote:
| 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.
| xyzzy123 wrote:
| I think there's also a dynamic related to pay that's not
| often discussed.
|
| 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.
| tikkabhuna wrote:
| 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.
|
| They all seem quite fulfilled, too.
| beaconstudios wrote:
| 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.
| mst wrote:
| 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.
| DnDGrognard wrote:
| 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.
| mst wrote:
| The fact that people may not know which is the relevant
| site is why https://gov.uk/ exists.
| avianlyric wrote:
| 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.
| Symbiote wrote:
| For people who aren't British or UK-resident, a reasonable
| example would be working out how to move to the UK for a job
| -- what visa to apply for.
|
| Start at https://www.gov.uk/
| ImaCake wrote:
| 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.
| aigo wrote:
| 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.
|
| [0] https://literacytrust.org.uk/parents-and-
| families/adult-lite...
| dash2 wrote:
| 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.
| ssl232 wrote:
| 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!
| iam-TJ wrote:
| Fortunately there's an FAQ^h^h^h Story about that: "A GDS
| Story"
|
| Introduction
|
| The most common questions we're asked by visitors to GDS
| are things like: "How did it all start
| in the first place?" "How did you get where you
| are now?" "How can I get my
| government/team/organisation to do similar things?"
|
| This is an attempt to answer those.
|
| https://gds.blog.gov.uk/story/
| dazc wrote:
| In general, I agree. However, as someone with an individual tax
| account, 2 business tax accounts and one general purpose
| account, far from perfect.
| dash2 wrote:
| I find the individual tax return very simple. Compare it to
| the misery they have in the US.
| midasuni wrote:
| So is solving formats last theorem
| drstewart wrote:
| The individual tax return in the US is very simple for 90%
| of people
| desas wrote:
| 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.
| mellavora wrote:
| I'm not sure about that 90% figure, seems a little high.
|
| 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.
| kube-system wrote:
| I just went to look up how many people file the 1040EZ,
| and realized that it doesn't even exist anymore. Today I
| learned.
| dazc wrote:
| So it is but I would strongly recommend you speak with an
| accountant before doing your own tax returns.
| sbacic wrote:
| 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.
| spion wrote:
| Given that this appears to be a page about a frequently asked
| question, I guess they have at least one.
| unbanned wrote:
| FAQs are needed for, poorly accessible information, poor
| communication with feature rollout, poor onboarding.
| bell-cot wrote:
| 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.
| moksly wrote:
| 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.
| retube wrote:
| > TypeScript/JavaScript (where the documentation is horrendous)
|
| Clearly you've never had to do anything in VBA....
| adwn wrote:
| > _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]
|
| [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
| lupire wrote:
| it says it rifht there: "timeout, input, check, and
| capture_output are not."
|
| For everything else, you have to consult Popen because it's
| Popen's API.
| camillomiller wrote:
| 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.
| lobocinza wrote:
| 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.
| vbezhenar wrote:
| 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.
| dr_zoidberg wrote:
| > 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.
| noisy_boy wrote:
| 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.
| bmn__ wrote:
| > 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.
| bccdee wrote:
| 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.
| blakesley wrote:
| Isn't it more natural that the summary comes first,
| before the details?
| bccdee wrote:
| 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.
| mjburgess wrote:
| dir(module) help(module.fn)
| kqr wrote:
| 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.
| throw10920 wrote:
| 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.
|
| [1] https://documentation.divio.com/
| asdff wrote:
| 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.
| kqr wrote:
| 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.
| pvaldes wrote:
| > I still haven't figured out how to get a good overview
| of the functions available in R
|
| 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
| Gunax wrote:
| I barely know it, but my brief experience with clojure has
| inspired me on how documentation should work.
|
| 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.
| blakesley wrote:
| 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.
| toast0 wrote:
| 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.
| ascar wrote:
| 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
| slaymaker1907 wrote:
| My biggest grip with Python documentation is that it often
| leaves flags and options underdocumented.
| OJFord wrote:
| 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.
| FooBarWidget wrote:
| 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.
|
| Ultimately, I think documentation should be split up into
| multiple categories, ala https://documentation.divio.com/
| Izkata wrote:
| Python is about 4 years _older_ than Java (based on
| "initial release" listed on Wikipedia), so the pattern
| still fits between those two languages.
| chaxor wrote:
| Java is a newer language though isn't it? The 90's wasn't
| so long ago... right guys?
|
| ... guys? :(
| wongarsu wrote:
| 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.
| stevula wrote:
| 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.
| mrsuprawsm wrote:
| 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.
| asdff wrote:
| 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.
| rhaksw wrote:
| > If people are frequently asking the same question then your
| information and how you deliver it is lacking.
|
| 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.
| ozim wrote:
| 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.
| trutannus wrote:
| > 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.
| thesuitonym wrote:
| 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.
| thenoblesunfish wrote:
| 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.
| Closi wrote:
| 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.
| antisthenes wrote:
| FAQs are great for not-very-frequently updated content of
| moderate complexity and finite scope.
|
| Something stable enough that 80%+ of the FAQ will remain relevant
| 5 or 10 years down the line.
| vmoore wrote:
| Anyone else _know_ a site has an FAQ but would rather reach out
| on social media, despite the careful inclusion of an FAQ?
| Abimelex wrote:
| 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.
| tlocke wrote:
| 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.
| c0balt wrote:
| 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.
| UweSchmidt wrote:
| 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.
| dspillett wrote:
| _> 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).
| DnDGrognard wrote:
| 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.
| asdff wrote:
| 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."
| SmartestUnknown wrote:
| 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.
| dblock wrote:
| Or your entre website can be the FAQ.
|
| https://www.drawingwithrussians.com/faq.html
| ValentineC wrote:
| The concept is fabulous. I hope to be able to attend this if
| I'm ever in New York one day!
| richrichardsson wrote:
| I don't agree with:
|
| > "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?
| shikoba wrote:
| Maybe FAQs are just a simplified manual. Those are often
| missing. I don't want to read a 30 pages manual before using
| something.
| majkinetor wrote:
| 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.
| akvadrako wrote:
| 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.
| dmitriid wrote:
| > FAQs should cover common edge cases.
|
| If these cases are _common_ , they are not edge cases, and
| they should be described in the actual documentation,
| guides etc.
| mst wrote:
| 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.
| dash2 wrote:
| Doesn't a manual also show you've thought about what your users
| should know, but not about your users?
| spawarotti wrote:
| Isn't Stack Overflow one big FAQ? So arguing FAQs shouldn't exist
| is like arguing SO shouldn't exist? Nice in theory, but in
| practice...
| gpmcadam wrote:
| > 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:
|
| Ironic?
| tomcart wrote:
| Erm: https://www.gov.uk/search/all?keywords=faq&order=relevance
| alecbz wrote:
| I think this is coming from one particular government
| department, not all of gov.uk
| necovek wrote:
| > We are often asked...
|
| 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.
| chrnad wrote:
| 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.
| gouggoug wrote:
| This article argues FAQs _don't_ help you know what you don't
| know at a quick glance.
|
| > questions take longer to scan and understand than simple
| headings and you can't take any meaning from them in a quick
| glance.
| walshemj wrote:
| The article also getting on for almost 10 years old.
| globular-toast wrote:
| The comp.lang.c FAQ is one of my favourites: http://c-faq.com/
| low_tech_love wrote:
| 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".
| jcims wrote:
| 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.
| DnDGrognard wrote:
| Someone doesn't understand how google works these days - sounds
| like an excuse for not putting the work in.
| pdpi wrote:
| 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.
| DnDGrognard wrote:
| Have you actually used Google recently? the FAQ and PAA
| results are what you would want to target with faq pages.
|
| 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"
| lupire wrote:
| They are basically saying "We don't make mistakes so we dont need
| FAQs" with a dash of "we don't know how Hyperlinks or Transfusion
| works".
|
| It's Incompetence painted over with Hubris.
| mcmUK wrote:
| FAQs are for seeding Google with answers to questions people are
| asking about your products and services off-site.
| Veen wrote:
| 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.
|
| [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".
| onion2k wrote:
| 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.
| [deleted]
| zestyping wrote:
| This is surprising to me. I often find FAQs pretty useful.
| reedf1 wrote:
| I think they are useful to an expert user.
| lmm wrote:
| 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.
| o_m wrote:
| 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.
| tikkabhuna wrote:
| 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.
| newaccount74 wrote:
| I disagree. FAQs are very useful.
|
| 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.
| ozim wrote:
| 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.
| adrianmonk wrote:
| You could say that, for an FAQ to work how it's supposed to,
| the Qs need to be real Qs and need to actually be FA.
|
| But yeah, even though that seems pretty self-evident, people
| manage to mess it up anyway.
| newaccount74 wrote:
| Stack Overflow is not a FAQ. Stack Overflow is a Q&A site
| with millions of questions.
|
| A FAQ is a list of 5-20 questions that quickly answer
| questions without having to read the docs or trying your luck
| on Google.
| akyoan wrote:
| 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.
| jsharpe wrote:
| 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.
| jollybean wrote:
| Perhaps FAQs should just reference the material, that way they
| don't go out of date.
| softwaredoug wrote:
| I disagree with the duplication point.
|
| 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.
| rkangel wrote:
| 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!
| marcosdumay wrote:
| Most people do not queue up to buy iPhones.
| rkangel wrote:
| I didn't mean it literally (at least these days). But I
| don't think you can deny that iPhones are incredibly
| popular with everyone.
| marcosdumay wrote:
| Most people don't buy anything from Apple.
|
| You just decide that it's ok to require everybody to do
| things the same way because a group of people buy some
| stuff that gives them no choice.
| anotheryou wrote:
| 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.
| frosted-flakes wrote:
| 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.
| low_tech_love wrote:
| "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.
| jquast wrote:
| FAQ was for newsgroups, to reduce the noise of so many people
| asking the same questions, answered by "read the FAQ" which was
| usually posted periodically, http://www.harley.com/usenet/usenet-
| tutorial/faqs-frequently...
| alilleybrinker wrote:
| 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.
|
| Still learned a lot writing it though!
|
| [1]: https://prev.rust-lang.org/en-US/faq.html
| james_in_the_uk wrote:
| _Why don 't I agree with this?_
|
| 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.
| cannabis_sam wrote:
| 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..
| junon wrote:
| 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.
| fudged71 wrote:
| 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
| walshemj wrote:
| Try " renew driving license" in the UK the first PAA link is
| for freaking Dubai.
| marginalia_nu wrote:
| FAQs are great. Look at this:
| http://www.walshcomptech.com/repairfaq/REPAIR/whole/F_monfaq...
|
| I don't even have a CRT monitor and I still cherish that
| document.
| yawnxyz wrote:
| 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"?
| RedNifre wrote:
| This is not surprising to me. I never ever found my questions in
| any of them, thus reading them has always been a waste of time
| for me.
| LudwigNagasena wrote:
| > Twitter agrees
|
| 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.
| sva_ wrote:
| > terminally online
|
| 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
| watwut wrote:
| In an odd roundabout way, "terminally online" or "extreme
| online" are terms used on twitter and pretty much nowhere
| else.
| gouggoug wrote:
| 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.
| Angostura wrote:
| I normally have the highest regard for GDS, but I'm entirely
| convinced they are correct in this case.
|
| 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
| leephillips wrote:
| 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."
| patwolf wrote:
| 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.
| thesuitonym wrote:
| 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.
| asdff wrote:
| 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.
| skyeto wrote:
| 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)
| majkinetor wrote:
| FAQ is valuable. You cant mistake FAQ for bad or incomplete
| documentation. Its just one focused document on particular
| aspects of the entire system.
|
| People ask about the same or similar things, its a known
| phenomena. People don't RTFM and manual may be overwhelming. You
| get value in reading the most frequent questions as a user too,
| and although all the facts can be deducible from the manual, they
| are here on one place now, isolated from the rest of the docs.
|
| Compare this to quick/short introduction most manuals have and
| you get the same duplication problems and the same beneficial
| points.
|
| In conclusion, FAQ is legit.
| mankyd wrote:
| Agreed. Honestly, I often jump to a faq early in my research
| when I'm thinking to myself: "just give me the highlights."
|
| It's context dependent though. If it's a one page, cliff notes
| style faq, great. If it's a large, searchable, knowledge base,
| then that's just documentation masquerading as a faq - often
| poorly so.
| Veen wrote:
| > I'm thinking to myself: "just give me the highlights."
|
| That's the problem though. The "highlights" should be front-
| and-center in the main content. If it isn't then the content
| is poorly designed, and the FAQ is just a way of working
| around bad content without fixing it.
| atoav wrote:
| > 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.
| LudwigNagasena wrote:
| But how can you write the information in the right way for
| everyone? I can imagine dozens of different customer journey
| maps for the gov.uk website. It seems useful to maybe
| duplicate some information here and there to make different
| customer journeys more straightforward.
| avianlyric wrote:
| > 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.
| majkinetor wrote:
| > if you write your information in the right way, people
| won't need a FAQ
|
| Such thing doesn't exist.
|
| You are ignoring the complexity of human beings. There is no
| one solution fits all. I for instance don't like narrative
| docs, but factual, math like. Most people don't.
| notriddle wrote:
| By definition, an FAQ covers the common cases, not the full
| complexity of human beings. The long tail of edge cases
| need a full reference manual, not an FAQ.
| majkinetor wrote:
| FAQ covers 1 use case. It doesn't cover complexity. The
| entire docs is for that.
| onion2k wrote:
| _manual may be overwhelming_
|
| You've identified the problem right here. Writing FAQs avoids
| solving it.
| majkinetor wrote:
| "Overwhelming manual" is not objective thing. Some domains
| need to have overwhelming documentation because they are so
| complex. Even with careful design of such docs (i.e.
| progressive disclosure, cross linking etc.) it still can be
| overwhelming and it depends on your background.
|
| It also ignores the context - I create gov services, and
| people are mandated to use them by the law, not because they
| want to. No amount of design will solve that. They come to
| spend as low amount of time as possible in order not to have
| legal repercussions.
| onion2k wrote:
| _I create gov services, and people are mandated to use them
| by the law, not because they want to. No amount of design
| will solve that._
|
| The article that this thread is about is written by someone
| on the UK government digital service team. The UK
| government puts _significant_ effort into doing exactly
| what you say isn 't possible. The GDS team solve those
| exact problems by designing services that users can easily
| use without FAQs (or even looking at the documentation in
| most cases).
|
| And, as a British person in the UK who uses the
| government's websites a bit, I have to say they do a
| _really_ good job of it.
|
| If you believe designing government services means you
| can't design them well and make them easy to use then I
| suggest you invest time reading the GDS blog. You will
| learn _a lot_.
| majkinetor wrote:
| The GDS team works on portal to other services.
|
| I design services which are way more complex. Think of
| stuff like budget execution or online banking. Not the
| same problem.
|
| > And, as a British person in the UK who uses the
| government's websites a bit, I have to say they do a
| really good job of it.
|
| I agree. When I was working on similar website for our
| government, I used UK.gov as a reference.
|
| > If you believe designing government services means you
| can't design them well and make them easy to use then I
| suggest you invest time reading the GDS blog. You will
| learn a lot.
|
| I didn't say that. My services are very easy to use, but
| still have massive documentation.
|
| And no, I learned from GDS 10 years ago. They can
| probably learn from me now. I have way more experience
| and countless public services with total of around 100M
| users on all of them.
| onion2k wrote:
| _I design services which are way more complex._
|
| 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.
| majkinetor wrote:
| 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.
| avianlyric wrote:
| > The GDS team works on portal to other services.
|
| 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.
| majkinetor wrote:
| > 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.
___________________________________________________________________
(page generated 2021-12-07 23:02 UTC)