Outline README sections for a migration CLI and explain persuasion
Tests information architecture and developer persuasion. Strong answers sequence: hook, one-line install, runnable quickstart, comparison table, then config. Front-loads time-to-value and tackles migration pain.
What's really being asked
This question evaluates your ability to structure technical documentation as a persuasion and onboarding funnel rather than an unstructured brain dump. The interviewer cares about information hierarchy, developer experience friction, and product thinking applied to open-source adoption. Specifically, they want to see if you understand that a README is a landing page that must earn trust and demonstrate value within seconds.
The full answer
A strong response outlines six sections in this exact order. First, a one-line hook and badges that state what the tool does and its build status. Second, a copy-paste installation command that works in under ten seconds. Third, a runnable quickstart example showing a real migration file and the CLI command to apply it, because developers believe working code more than descriptions. Fourth, a comparison table against alternatives like Flyway, Liquibase, or Alembic that explicitly addresses why someone should switch. Fifth, configuration and usage depth for when the developer is already convinced. Sixth, contribution guidelines and license to signal a healthy community. The candidate should explain that this order mirrors the adoption decision funnel: attention, then proof, then trust, then depth.
The mistakes people make
Red flags include starting with system architecture diagrams or design philosophy before stating what the tool does. Another failure mode is burying installation instructions below the fold or omitting copy-pasteable commands in favor of narrative prose. Treating the README as an internal wiki with long deployment runbooks also signals weak product sense. Finally, omitting a comparison section suggests you have not thought about competitive differentiation or real developer trade-offs.
What usually comes next
The interviewer may ask how you would measure README effectiveness, so be ready to mention time-to-first-migration or GitHub traffic-to-star conversion. They might also ask how the README changes for an enterprise versus hobbyist audience, or how you would maintain it as the tool evolves.
A concrete example
For the database migration CLI, the quickstart should show a three-line SQL migration file and the exact terminal command to run it, producing colored output that is visible in an asciinema gif. The comparison table should list Flyway and note that your tool requires zero JVM overhead and uses plain SQL rather than XML. This proves you understand both the technical audience and the competitive landscape.
Interview question
Why should a migration CLI README place a comparison table against alternatives before the detailed configuration reference?
- a.Developers evaluating tools need to justify switching costs before they will invest time learning configuration detailsCorrect
- b.Technical readers prefer to scan alternatives after they have fully mastered the tool's settings
- c.Configuration options change frequently, so placing them later reduces maintenance burden
- d.Comparison tables improve GitHub SEO ranking when placed in the first half of the document
Why? this is the answer
Developers must understand competitive differentiation and justify switching before investing in configuration details, matching the attention-to-trust adoption funnel. Option C raises a valid docs concern but misattributes the ordering rationale, since the sequence serves persuasion rather than maintenance ease.
Just read this? Test yourself on what you have been reading.
Read the original → docs.github.com
- #documentation
- #developer-experience
- #technical-writing
- #open-source
- #product-thinking
You just looked this up. Could you explain it out loud?
That is the part interviews actually test. Tezvyn takes questions like this one and gives you what the interviewer is really checking, the answer that lands, and the mistake that ends the conversation, in the four minutes before your next meeting.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on documentation — each one lists the topics its interview covers.
See open roles