4

I think it happened to everyone, having side projects, trying to do something new and big in their spare time, or maybe having a little startup where everyone has clear in their mind what the software will do and what are the design goals to address.

I was wondering what type of documentation has to be produced under these circumstances? Since the client and the analyzer are the same person, many of the models of communications are useless, at least in most of contexts. But it's useful to track requirements and changes, especially if the software is big and complex.

What's the documentation that must be provided for self-produced software? Are there examples of documents drawn up for open source software?

  • 10
    There's always a client, even if it's just yourself. You don't need any documentation at all, but you do have to live with the consequences of not having any. – Robert Harvey Jan 7 '18 at 2:11
  • 1
    Clearly you always have to analyse what the requirements are, otherwise you'd be aimless. The purpose of written requirements is either to communicate that analysis to others, or possibly as an aide-memoire for yourself if the requirements are subtle or complex, but don't bear the overhead unless you need to - often, hobby side-projects are somewhat experimental (either to learn about a new problem domain, or to research how to integrate a solution to multiple problems or constraints), and are expected to be analysed alongside and after the implementation rather than before. – Steve Jan 7 '18 at 10:31
4

I think you're asking two somewhat different questions:

(Smaller) Side Project

For personal side projects, you obviously don't want to write a thousand pages of requirements specification - in fact, you rarely want to do this for any project, but especially not in this context.

Personally, I would still recommend writing down the requirements for the next small batch (2 to 8 hours of coding) just to keep you focused. At least for me, scope creep is a particular danger in personal projects.

Startup or Team Project

[...] where everyone has clear in their mind what the software will do and what are the design goals to address.

Trust me, they don't! Even if everyone has the same understanding today, how about tomorrow?

As soon as you're working on a team, write things down. People need to be able to refresh their memory on what the goals are precisely.

You don't have to specify the whole project down to the last detail, of course. But you really need to make sure everyone's on the same page with regards to the next feature. And that usually requires writing it down.

How much do you need to write down? That depends on team size, experience, interdependence, etc. and is hard to answer in general.

10

The is no general answer to this question. Without external requirements, such as a project manager, other developers, a boss, a regulatory agency, and so on, there is no answer other than you need whatever you need to drive a satisfactory outcome.

If that sounds tautological, consider that even on a side project, with no expectation of income, and no upper or lower bounds on how much time is invested, you still face actual reality at the end of the day. Time spent on the project is time not doing something else (opportunity cost). Maybe it's time with family, exercise time, or... even another side project that would have been more useful.

Your project already has requirements: they are in your head in some form or another. Maybe that's sufficient. If not, find a tool which provides clarity on what it is you're really trying to get out of the project, and what costs are acceptable to bear in doing so.

  • Thank you for the answer, and sorry if I'm late. Do you know some tool that does what you said? – Cristian Traìna Jan 28 '18 at 14:49
4

Do I need requirement analysis if there's no client?

Requirements analysis includes things like identifying stakeholders, gathering requirements, ensuring they are good requirements and resolving conflicts, and recording requirements. These things always happen, to one degree or another, on every project. You can't build anything if you don't know who you are building it for and what it is you are going to build. It doesn't matter if you are building it to solve a problem you are experiencing, are learning something new, or are making something for someone else.

What's the documentation that must be provided for self-produced software? Are there examples of documents drawn up for open source software?

There's never a set of documents that always must be provided for any project. If you're working for an organization, they are likely to have standards. If you are working for a client, they probably have some required documentation artifacts. The types and amounts of documentation should be enough to help the project succeed.

2

If you don't have requirements...

  • How do you know the actual progress you've made?

  • How do you know what's the next features you want to develop?

  • How do you know what's your project about?

You don't have to write the boring enterprise-ready document you (and probably all of us) hate... With some README.md where you define the system you want to create, the main features you want to develop, the possible clients/users/roles you could have, the possible roadblocks you might face... That'd be enough.

I'm telling you this because I need to plan everything I'm going to do because, otherwise, I get lost and start wandering. There are other kinds of people that can make progress without plans.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.