Ask HN: How to Write a Specification? | Hacker News Reader

Ask HN: How to Write a Specification?

11 pointsnabi_nafio11 comments

I am planning to build a product (web app), and want to write a spec before starting to code. I have never written a spec before. My question is: how to write a specification?

View on HN

An alternative to writing a formal specification: write you app's 'readme' before you start any coding. An 'readme' can be more approachable than a formal specification. The idea is called 'Readme Driven Development'.

This article describes more:

Readme Driven Development: https://tom.preston-werner.com/2010/08/23/readme-driven-deve...

This is really interesting. Thanks for your suggestion.

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 "big decisions" 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 "shall" statements in binders.

But start with Joel Spolsky's classic "Painless Functional Specifications" (read the whole series) and you'll be starting in a good place.

https://www.joelonsoftware.com/2000/10/02/painless-functiona...

Thanks for sharing this.

Hey! I know this is a bit late, but Part 1 of Basecamp's book "Shape Up" might be helpful too. It's not explicitly about specs, which is probably why I didn't think of it before, but it's worth a skim.

https://basecamp.com/shapeup/webbook

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.

Goals are things like: user data entry is appreciably faster. Contrast that with "how" statements like "all user data entry will be on one screen" which only hints at the true motivation and may end up being in tension with the true motivation.

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't guaranteed (e.g., we will not be putting effort into reducing our cloud spending as part of this project).

Anti-goals are things that you explicitly want to prevent from happening — we do not want to purchase new servers for this project. These "anti-goals" are often non-functional goals in more formal frameworks.

If you are uncertain about the utility of a project, starting with a "motivation" section can be a helpful exercise.

There are numerous templates, e.g. http://web.cse.ohio-state.edu/~bair.41/616/Project/Example_D... which you can find by searching with additional search terms relevant to the technology, intended users, etc.

There are many 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.

* Provide a version and/or date.

* If the title insufficiently describes purpose in five words or less then provide an abstract.

* Describe your terms. This is your primary opportunity to achieve precision, don’t waste it.

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

* At the end provide limits on the scope of criteria and any security concerns.

TL;DR work top down

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/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'll try to narrow down to your specific case of the web app, and will omit more heavyweight or formal methodologies.

It depends on what this web app does, for whom you're writing this spec, and how many people you are going to collaborate with, and whether they're technical or not.

If they're not technical use a Google Docs/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.

In case everyone is technical just use Github-flavored Markdown (GFM) stored in the project's git repo. You can start from RDD (Readme-Driven Development) as was suggested in another comment.

If it'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.

Use text-based formats like PlantUML or Mermaid where possible, and store them in the project's git repo. I like PlantUML, but Github now can render Mermaid in Markdown and Github issues natively.

If you define APIs using GraphQL, OpenAPI, AsyncAPI or similar - you're getting both typed schema and design/documentation for free.

For a relatively simple or single-feature app - Shape Up method's[1] mini-pitch format may help.

In case the app has a complex business logic - check out EventStorming[2]. It especially works well with DDD and CQRS/ES architecture.

Here's the hierarchy of the relevant methods as I see it:

  Freeform description (NDD - Narrative-Driven Development)
    Amazon PR/FAQ - 6-pager
      Blog post (BPDD - Blog post Driven Development, build in public)
        Product Brief / 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

Some of the relevant heavyweight spec formats:

- SRS - Software Requirements Specification

- SDD - Software Design Document

- PRD - Product Requirements Document

- ERD - Engineering Requirements Document (Uber)

- MRD - Marketing Requirements Document

[1] https://basecamp.com/shapeup

[2] https://www.eventstorming.com/

Reply on news.ycombinator.com