Skip to content

FAQ

A list of anticipated questions with direct, self-contained answers, ordered by how often they are asked.

A FAQ collects the questions a reader is most likely to ask and answers each one directly, ordered by frequency or by the reader journey. It optimizes for a reader who arrives with a specific question and wants a fast, self-contained answer, not a narrative. Each entry stands alone: a reader should never have to read the whole thing to get their one answer.

The shape of a FAQ reflects an understanding of the audience: the questions listed are the ones the audience has already demonstrated, not the ones the author wishes they would ask. Each answer should be the minimum necessary to satisfy the question. FAQ ordering is not alphabetical and not by author preference - it is a deliberate editorial decision about the reader, ordered by how often they ask or by the sequence of their journey.

## Frequently Asked Questions
### [Most frequently asked question, phrased as the reader would ask it?]
[Answer in 1 to 3 sentences. Self-contained. Do not reference other answers.]
### [Second most frequent question?]
[Answer. If the answer depends on a condition, state the condition first, then the answer for each case.]
### [Third question, often one that surfaces a common misconception?]
[Answer. Correct the misconception directly, then give the right answer.]
### [Next question...]
[Answer...]

A product, service, or process generates a predictable set of recurring questions from users or customers, a landing page or onboarding flow needs to pre-empt common questions before the reader reaches a support channel, a policy or process document needs a companion that handles reader questions without bloating the main doc, support documentation where readers arrive with a specific question and need a fast targeted answer, after a product update, policy shift, or launch that will generate a burst of similar questions.

When the content is a precise technical specification with syntax, parameter definitions, or code examples - use a technical reference instead. When no genuine set of recurring questions exists and the format would organize general information that belongs in a guide or reference. When the topic is complex enough that each question requires extensive context to answer accurately - a guide or tutorial serves that reader better.

technical-writer, friendly-mentor, instructional, matter-of-fact, question-and-answer

technical-reference: Both formats serve a reader who arrives with a specific lookup rather than reading straight through. The difference is content: a FAQ collects recurring natural-language questions with self-contained prose answers, ordered by reader frequency; a technical-reference is a precise specification of syntax, signatures, parameters, fields, and code examples. A FAQ answers “How do I…” or “What happens if…”; a technical-reference documents exactly how something is defined.

  • Questions written in the reader’s own words, often starting with “How do I”, “What is”, “Can I”, or “Why does”
  • Each question-answer pair is a complete, self-contained unit readable without the others
  • Ordered by frequency with the most common question first, or by reader journey stage
  • Answers are brief by design - typically one to three short paragraphs - and link out rather than elaborate inline
  • No transitional prose between pairs; the pairs stand in parallel, not in sequence
  • The question is phrased as the reader would ask it, not as the author would label the topic
  • Phrasing questions the way the author thinks about the topic rather than the way the reader asks - A reader searching for help with a forgotten password will not find a section titled “Account credential management procedures”; the question must match the reader’s own phrasing.
  • Expanding answers into multi-paragraph tutorials that require the reader to read through to reach the point - Self-containment and brevity are the format’s only advantages over a narrative doc; long answers erase both and signal the content belongs in a guide, not a FAQ.
  • Using a FAQ to house precise technical specifications - syntax tables, parameter lists, field definitions, code examples - rather than natural-language question-answer pairs - A FAQ collects recurring natural-language questions with self-contained prose answers; a technical-reference is a precise specification of syntax, signatures, parameters, fields, and code. Blurring the two produces a document that does neither job well.
  • Ordering questions alphabetically or by an author-chosen grouping instead of by reader frequency or journey - FAQ ordering is an editorial decision about the reader, not the author; author-centric ordering buries the most common question where readers stop looking.
  • Over-atomizes - the format tips into a list of one-sentence stubs where every question gets a non-answer too brief to satisfy anything - Each answer must do actual work; if the answer is shorter than the question, the question is probably out of scope for a FAQ, or needs one more sentence of genuine substance.
  • Over-populates - the format tips into an exhaustive catalogue of every possible question, including rare edge cases, until the common questions are buried in volume - Audit by frequency; remove questions that only a small fraction of readers will ask and move edge-case depth to linked reference material rather than expanding the FAQ itself.
  • Over-isolates - each answer restates so much background context to be self-contained that answers balloon into repeated mini-essays and the document becomes bloated - Self-contained means the reader does not need to read other answers to get their answer, not that each answer must recap the whole product; shared context belongs in a brief preamble, not repeated in every entry.
Write as a FAQ (Frequently Asked Questions). Structure the content as a series of discrete
question-answer pairs. Phrase each question the way the reader would actually ask it, not the
way you would label the topic. Each answer must be self-contained: the reader jumping directly
to that pair should get a complete, useful response without needing to read other pairs. Order
pairs by frequency (most common first) or by reader journey stage (orientation before
troubleshooting). Keep individual answers brief - one to three short paragraphs - and link to
deeper resources rather than elaborating inline. Do not write transitional prose between pairs.
If an answer requires extensive length to be accurate, the question probably belongs in a guide,
not a FAQ.

See the FAQ template.

Technical Writer, Friendly Mentor, Instructional, Matter of Fact, Question and Answer

Confessional, Columnist, Reverent

Technical Reference

Frequently Asked Questions - Async Standup

Section titled “Frequently Asked Questions - Async Standup”

Is the 9am Pacific standup still happening?

Section titled “Is the 9am Pacific standup still happening?”

No. The synchronous daily standup is replaced with an async update posted to #team-standup. There is no call to join. The old calendar invite has been removed.

By 10am your local time, every weekday. That is 10am Pacific, 10am Eastern, 10am UK, or 10am IST depending on where you are. Posting at the start of your morning helps the on-call engineer triage the channel before their midday.

Use the three-field template pinned in #team-standup:

  • Shipped: what completed in the last 24 hours
  • In progress: your current focus
  • Blocked or at risk: anything that needs attention, with an @mention of the person who can resolve it

Keep the whole post to under 60 seconds of reading time. If a field is empty, write “nothing today.”

What if I’m blocked and need help right now?

Section titled “What if I’m blocked and need help right now?”

Add your blocker to the “Blocked or at risk” field and @mention the person who can resolve it directly in your standup post. The on-call engineer scans #team-standup once between 10am and 11am Pacific and makes sure every @mention has a response before end of the workday. If the situation is urgent, DM or post in #team-dev directly - the async standup does not replace direct communication for critical blocks.

The 9am Pacific standup was 9:30pm for engineers based in India, and Q1 attendance data showed the gap: India-based engineers averaged 3.2 appearances per week versus 4.6 for US-based engineers. Beyond the timezone problem, the 14-minute meeting was producing roughly 4 minutes of information that changed anyone’s behavior, and none of it persisted after the call. Three times last quarter an engineer spent an hour on a problem already solved in a previous standup because there was no searchable record. The async format lets everyone participate at a time that fits their day and creates a record that survives the call.

What happened to the 9am slot on my calendar?

Section titled “What happened to the 9am slot on my calendar?”

The time that was five standup sessions per week is now one Thursday working session, 60 minutes, at 8am Pacific (8:30pm IST). Agenda lives in docs/thursday-agenda.md. The session is reserved for topics that genuinely require real-time conversation. If the agenda is empty by Wednesday at 5pm Pacific, we cancel.

Who makes sure blocked items don’t fall through?

Section titled “Who makes sure blocked items don’t fall through?”

The on-call engineer is responsible for scanning #team-standup once between 10am and 11am Pacific each weekday. Their job is to confirm every @mention has a response before end of day - not to summarize the channel for everyone else. This on-call reading responsibility replaces the meeting facilitation duty that was on the same rotation.

Post when you remember. A late post is better than no post. If you miss a day entirely, there is no correction needed - just resume the next morning. Chronic gaps hurt the channel’s value for everyone, but a single missed day is not an incident.

Is this permanent or are we still deciding?

Section titled “Is this permanent or are we still deciding?”

This is a 30-day trial. The retro document is docs/trial-retro.md. If you have feedback mid-trial, add it there rather than in DMs or side conversations. The decision to keep, adjust, or revert will be made at the Day 30 retro with input from the full team.