Ask HN: Do you write specs/requirements for things you work on, do you like it?

[MarkoSustic]

Hi, i am wondering, now that i am starting a new startup what are best practices around specs/requirements:

1. Do you/your team write product specifications/requirements diligently? 2. Do you like writing them? 3. Who in your organisation/team is doing it? 4. How frequently are you doing it? 5. How do you maintain them? (if change happens) 6. What tool do you prefer to collect requirements? 7. Do you use some templates or standards while writing them, like is there any standardised formatting? 8. Any advice how to format it for best results? 9. Open answer what ever comes to mind, conversation theme should be clear by now.

Answer one or more, everything is welcomed, i hope this helps me and others wondering the same.

Thanks

[axilmar]

Requirements always exist in a project, even if they are not written.

And how they cannot exist, since the only reason a program is written is because of some need...

And since requirements always do exist, they better be in written form, so as that they can be referenced, tested, discussed etc.

In previous projects, JIRA was used. In the current project, an internal tool is used, pretty much similar to JIRA.

In some older projects, a simple Word document was used and an Excel sheet for tracking progress.

Writing a requirement should be simple enough: it shall either define things, or describe processes and their side effects.

It is better to have a dedicated person to write them, because the wording and style of requirements should be consistent, and the person that writes them will gradually be more and more experienced in writing better requirements.

Having good requirements makes it a lot easier for developers to write the required programs.

[sloaken]

1 current organization does not, but I am trying to get them to. It is necessary for long term maintenance. How do I fix something when I do not know what it is required to do.

2 I do not, nor do I know anyone who does. Except user seabass-labrax But I see it as essential.

3 depending on organization, but generally they have to be knowledgeable in the frame of the customer (internal or external) needs. Other places I have worked the sales team had a large influence.

4 if it is not a short term, or throw away code when the developer leaves (from winning the lottery). Then anything worth doing is worth doing right.

5 it will change, and you have to plan on that.

6 there are fancy tools but I find them cumbersome to learn, and often default to word and / or spreadsheets

7 I expect with any requirement to have listed with it where it came from. Be it my initials, a particular meeting, a government regulation. In a serious production, you trace the requirements to design, implementation and test procedures. With recording dates of passing tests. My current one will not have all this tracing.

I like to put Wants in the requirements, and list them as such. Basically I am kicking the issue down the road for someone else to decide if it is a need.

Remember: if you cannot test it, it is not a requirement.

[MarkoSustic]

this is super valuable insight to me. I would agree with you, i have experience in how it is done in large complex organisations and i had awareness that in less organised smaller orgs its not done with traceability etc. One theme i notice is that people, especially creative people don't like doing it, but find it necessary as they see all the issues coming from not writing or having specs/reqs. But this insight you gave is super useful for me. Thank you!

[sloaken]

One last comment: When writing up requirements, be careful to not put implementation details as requirements. For example: let us say you are a IBM mainframe / COBOL. Putting in IBM and or COBOL as a requirement would restrict the development that might choice a raspberry Pi running Slackware and Java. And of course the reverse is true, despite being unlikely.

There are probably some good books / online classes on the topic, worth a weekends time.

[seabass-labrax]

Interesting question. From my background in FOSS and open standards, one of the most common ways for possible changes to be made is the 'Request For Comments' (RFC).

1., therefore, is yes: many of the FOSS projects in involved in do write requirements specifications as part of an RFC process.

2., yes, I enjoy it. Not everyone does, but describing a proposal in great detail can clarify your own imagination of what it could be like, and can preempt inevitable questions. This saves everyone's time.

3., generally only long-term contributors, the 'shakers and movers' of a project. External or one-off contributors tend to suggest changes on issue trackers or chatrooms instead; this is partly because some don't want to make any commitment to shepherd the RFC through, but also because they don't necessarily have the background knowledge to know which questions to pre-emptively answer.

4., variable depending on the project. Small changes, that is, ones that don't affect much outside of their immediate context, don't usually have RFCs. It would be a waste of time for typo fixes, for instance.

5., I think this is very important: there should be a time limit on RFCs. The worst thing is when you have proposals that linger on for months or years and nobody quite knows how to move forward. Therefore, the leadership committee or whatever the responsible persons are called should give a clear yes-or-no answer after a fixed duration of public discussion.

7., absolutely, templates are expected.

8., "what other potential solutions have you considered?" is a classic question that every RFC submitter should answer.

9... well, nothing more really except good on you for taking technical change management seriously (a hard challenge, second only to cultural change management) and good luck :)