Ask HN: How to Write a Specification?

An alternative to writing a formal specification: write you app&#x27;s &#x27;readme&#x27; before you start any coding. An &#x27;readme&#x27; can be more approachable than a formal specification. The idea is called &#x27;Readme Driven Development&#x27;.<p>This article describes more:<p><i>Readme Driven Development</i>: <a href="https:&#x2F;&#x2F;tom.preston-werner.com&#x2F;2010&#x2F;08&#x2F;23&#x2F;readme-driven-development.html" rel="nofollow">https:&#x2F;&#x2F;tom.preston-werner.com&#x2F;2010&#x2F;08&#x2F;23&#x2F;readme-driven-deve...</a>

There are a lot of different levels of rigor you can aim for when writing a spec. But at its most simple, a spec simply captures what you want the product to do in enough detail that you can later focus on implementing. The &quot;big decisions&quot; are already made. It can be as simple as the classic napkin sketch, a few notes on a whiteboard, or hundreds of pages of extensively-reviewed &quot;shall&quot; statements in binders.<p>But start with Joel Spolsky&#x27;s classic &quot;Painless Functional Specifications&quot; (read the whole series) and you&#x27;ll be starting in a good place.<p><a href="https:&#x2F;&#x2F;www.joelonsoftware.com&#x2F;2000&#x2F;10&#x2F;02&#x2F;painless-functional-specifications-part-1-why-bother&#x2F;" rel="nofollow">https:&#x2F;&#x2F;www.joelonsoftware.com&#x2F;2000&#x2F;10&#x2F;02&#x2F;painless-functiona...</a>

Depending on the circumstances, I tend toward outcome-based documents that help define the what more than the how. The simplest form is to specify one or more of each of these: goals, non-goals, and anti-goals.<p>Goals are things like: user data entry is appreciably faster. Contrast that with &quot;how&quot; statements like &quot;all user data entry will be on one screen&quot; which only hints at the true motivation and may end up being in tension with the true motivation.<p>Non-goals are either things that are out of scope (e.g., we will not be introducing new fields to capture during this project) or things that would be fine if they happened as a side-effect but aren&#x27;t guaranteed (e.g., we will not be putting effort into reducing our cloud spending as part of this project).<p>Anti-goals are things that you explicitly want to prevent from happening — we do not want to purchase new servers for this project. These &quot;anti-goals&quot; are often non-functional goals in more formal frameworks.<p>If you are uncertain about the utility of a project, starting with a &quot;motivation&quot; section can be a helpful exercise.

There are numerous templates, e.g. <a href="http:&#x2F;&#x2F;web.cse.ohio-state.edu&#x2F;~bair.41&#x2F;616&#x2F;Project&#x2F;Example_Document&#x2F;Req_Doc_Example.html" rel="nofollow">http:&#x2F;&#x2F;web.cse.ohio-state.edu&#x2F;~bair.41&#x2F;616&#x2F;Project&#x2F;Example_D...</a> which you can find by searching with additional search terms relevant to the technology, intended users, etc.

There are <i>many</i> ways to do it. I personally recommend “Event Storming” as a great way to get started (web search it).

* Start with a title. The title must state the purpose of the document in as few words as possible and that purpose must be narrow in scope as there can be other documents for things out of scope.<p>* Provide a version and&#x2F;or date.<p>* If the title insufficiently describes purpose in five words or less then provide an abstract.<p>* Describe your terms. This is your primary opportunity to achieve precision, don’t waste it.<p>* The body of the spec should flow in a linear progression and read like an instruction manual. The goal is not entertainment but rather reference first with examples and proofs. Remember that writing instructions is not scholarly yet simultaneously most people cannot follow a series of simple instructions, so ignore audience reading level and be true to the subject matter.<p>* At the end provide limits on the scope of criteria and any security concerns.

TL;DR work top down<p>System engineer here. After noting any flow down requirements from higher levels (e.g. regulations, safety, security, language, operating system, usability, availability, quality, corporate standards, coding standards, maintainability, etc.), I find it useful to first define the highest level (context) of your system, write out the concept of operation and define the major interfaces and then work down&#x2F;in from there. A set of diagrams can really help with this process. And a spreadsheet and numbering system helps for traceability. Good luck.

There are lots of ways to write formal, semi-formal, or informal specs, but I&#x27;ll try to narrow down to your specific case of the web app, and will omit more heavyweight or formal methodologies.<p>It depends on what this web app does, for whom you&#x27;re writing this spec, and how many people you are going to collaborate with, and whether they&#x27;re technical or not.<p>If they&#x27;re not technical use a Google Docs&#x2F;Slides. In Google Docs you write a free-form description (prose). Or you can use Google Slides as a kind of scrapbook - you can capture every idea you have, and add any screenshots or diagrams you find related.<p>In case everyone is technical just use Github-flavored Markdown (GFM) stored in the project&#x27;s git repo. You can start from RDD (Readme-Driven Development) as was suggested in another comment.<p>If it&#x27;s a simple CRUD app, you can define a data model (an ERD), an API, draw UI mockups, draw message sequence diagrams, define background workflows, etc.<p>Use text-based formats like PlantUML or Mermaid where possible, and store them in the project&#x27;s git repo. I like PlantUML, but Github now can render Mermaid in Markdown and Github issues natively.<p>If you define APIs using GraphQL, OpenAPI, AsyncAPI or similar - you&#x27;re getting both typed schema and design&#x2F;documentation for free.<p>For a relatively simple or single-feature app - Shape Up method&#x27;s[1] mini-pitch format may help.<p>In case the app has a complex business logic - check out EventStorming[2]. It especially works well with DDD and CQRS&#x2F;ES architecture.<p>Here&#x27;s the hierarchy of the relevant methods as I see it:<p><pre><code> Freeform description (NDD - Narrative-Driven Development) Amazon PR&#x2F;FAQ - 6-pager Blog post (BPDD - Blog post Driven Development, build in public) Product Brief &#x2F; 1-pager (Shopify) Pitch Mini-pitch (Shape Up method) Readme (RDD - Readme-driven Development) Breadboarding (Shape Up method) Fat marker sketch (Shape Up method) Lo-fidelity mock Hi-fidelity mock Clickable mockup Functional prototype alpha beta 1.0 </code></pre> Some of the relevant heavyweight spec formats:<p>- SRS - Software Requirements Specification<p>- SDD - Software Design Document<p>- PRD - Product Requirements Document<p>- ERD - Engineering Requirements Document (Uber)<p>- MRD - Marketing Requirements Document<p>--<p>[1] <a href="https:&#x2F;&#x2F;basecamp.com&#x2F;shapeup" rel="nofollow">https:&#x2F;&#x2F;basecamp.com&#x2F;shapeup</a><p>[2] <a href="https:&#x2F;&#x2F;www.eventstorming.com&#x2F;" rel="nofollow">https:&#x2F;&#x2F;www.eventstorming.com&#x2F;</a>