Outline README sections for a migration CLI and explain persuasion

WHAT THIS TESTS:

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.

A GOOD ANSWER COVERS:

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.

COMMON WRONG ANSWERS:

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.

LIKELY FOLLOW-UPS:

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.

ONE 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.

Source: docs.github.com