3 ms·
Related: https://www.joelonsoftware.com/2000/10/02/painless-functional-specifications-part-1-why-bother/ https://www.joelonsoftware.com/2000/10/02/painless-func
by dgb23 6y ago
Related: https://www.joelonsoftware.com/2000/10/02/painless-functional-specifications-part-1-why-bother/ https://www.joelonsoftware.com/2000/10/02/painless-functiona...
My opinion:
If you don't specify things in a separate document in the form of text and pictures, then you end up doing it anyway but ad-hoc.
Your "non-spec" now leaks into multiple tools and channels that likely don't talk to one another: emails, instant messages, file storage, notes, phone calls & discussions (AKA in your head/memory), Trello/Asana/Jira etc. and in peoples imaginations and expectations.
A specification is just the things you do anyway but instead written down in a single maintained place. You can source control it and iteratively change it. All the parties can pull it and look at it before/during/after iterations and discussions.
A spec doesn't need to be set in stone at all. It can grow/shrink/change iteratively with the thing you build. It can also define things that you specifically shouldn't do or worry about.
A "design doc" seems to be something like that with a different name?
Also a specification can help to communicate much more clearly, since you end up defining a vocabulary for processes, UI elements, technical components and so on.
Tools I find useful to do this:
- markdown + css + some tool to convert it to html/pdf
- graphviz, especially for state-machines and decision trees, I prefer output as SVG rather than PNG.
- UML diagrams or similar if applicable
- bigbizisverywyz 6y agoA really nice framework for specifying a system, I've found, is the vision document from RUP. It's great for putting the user front and center, and ensuring that you're building a system that people actually want and have a realistic business case.
- H8crilA 6y agoA design doc is not exactly a spec. It is a medium for discussion and a snapshot of what people thought at the time. They do get old pretty quickly and there's no expectation that anyone will update them (always put dates on such documents!). I think that specs should be checked into the codebase, either through some kind of code annotation, or next to it in text files, depending on what is it that you're doing.
- dgb23 6y agoThank you for clarifying. My question is: when do I need a design doc, given I already have a maintained spec? Would they be used for as drafts or are they a complete separate thing?
- maps7 6y agoI think a design doc is for when you don't know enough to spec a solution.
- joatmon-snoo 6y agoI tend to reach for a design doc when I have (1) an ambiguous problem, (2) no obvious solution but N possible candidates, and (3) need feedback from multiple parties. The primary functions (as people have mentioned elsewhere) are to (1) drive consensus and (2) record thought processes at the specific point in time.