3 ms·
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 hea
by nivertech 4y ago
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 https://basecamp.com/shapeup
[2] https://www.eventstorming.com/ https://www.eventstorming.com/