
Ask HN: When starting a new product build, how do you write out technical specs? - bryanmgreen
	I&#x27;m working on a new project and have been recently thinking about my spec writing process.<p>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&#x27;m not sure this is the most efficient.<p>How do you go about writing specs and what medium do you use?
======
alexeysemeney
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](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!

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

------
steejk
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](http://www-03.ibm.com/software/products/en/ratidoor)

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

