Ask HN: When starting a new product build, how do you write out technical specs?

https://news.ycombinator.com/item?id=11939612

by bryanmgreen • 10 years ago

13 6 10 years ago

news.ycombinator.com

I'm working on a new project and have been recently thinking about my spec writing process.

Depending on project size, I either have a team G-Doc or write a markdown file. We start with the big features and work our way down. I'm not sure this is the most efficient.

How do you go about writing specs and what medium do you use?

funnywalrus• 10 years ago

My company uses G-Docs but within a folder called Specs and each doc is a main category. A little easier track changes, but still kind of clunky.

sua_3000• 10 years ago

We use Epics in Atlassian's Jira. Each ticket is a feature story which together compose an Epic.

I have also seen Trello cards work well for recording specs

bryanmgreen• 10 years ago

I've used Trello in the past and it's been pretty useful for organizing, but I hate having to manually click on several cards if I want to do edits. It can take forever when you're trying to assemble a large amount of text.

steejk• 10 years ago

Not software engineering, but we (big corp) use IBM DOORs [0]. It's not the most intuitive, but the concept is you define feature requirements which cascade down to requirements in sub-levels.

[0] http://www-03.ibm.com/software/products/en/ratidoor

alexeysemeney2• 10 years ago

Hey Bryan, I have built several long term project myself (and continue to do so) and helped a ton of folks running http://devteam.space. Maybe you can apply this process to your new project (about medium below that). Here it is:

1. Project description. Plain simple explanation what your project does, etc. You might think it's an obvious and redundant thing. But it's not. It does help you to nail the project, define critical points and set all the team members with the same vision in mind. It should be 1/2 of the page.

2. User path. Describe how user finds you, sign up, start using it, what gets out of your project, why returns, and why be proud to tell others about it. If you build a marketplace/platform - build these stories for all types of users you have. This one is super important. It helps you to define bottlenecks, interface elements, user behavior, strong/week points, etc. It also can help you to describe your project to your potential users, so you could check if they are cool about using it. You might find you need to pivot without writing a line of code.

3. UI - describe it in the list form with several levels. It will help you to understand the real complexity of what you are building and delete unnecessary things.

4. Features list. You know how to do that already.

5. Tech specs. I guess you know how to do that too if this is not your first project.

6. Draw the UI on a paper. It will help the designer, and you will see some obvious things you should delete/add.

Medium - we use gdocs. Mind maps work well too because you can present the user path in a visual format and play with it changing pages/actions.

It sounds a lot, but man it saves so much time and resources down the road. If you need more advice - ping me at alexey(at)devteam.space - happy to help, good luck!

alexeysemeney2• 10 years ago

Ops, missed the "technical" in your question. Anyways, hope that helps.

Ask HN: When starting a new product build, how do you write out technical specs?

Related Stories