How imperative is the need of specifications being written down in case of a new project?

Question

I have a new project to deal with. I'm the only one to deal with it currently (a kind of a personal project). It's likely that in the future there will be more contributors to it.

Taking in account the best practices when it comes to talk about project management, how much is there a need for the project specifications to be written down? Is it imperative, or is it something that is left to the choice of development team?

N.B. By specifications I mean the set of guidelines that a developer uses in order to get implemented the targeted object of project involved.

Note: I'm not asking about subjective choices (although such examples are well appreciated). I'm asking about some theoretical aspects, if there are any, regarding this issue.

Answer 1

As with all things software, It depends on the complexity and context of a given project. The more tied you are to the risks of the project's success the better served you are by clear declarations of need/intent and deliverable results.

Are you an employee of the people/company that want's the project done? If so, having an iterative approach without a clear specification is acceptable.

Are you working on a fixed price bid? Having a clear specification is VERY important here.

Everything else is in between. In your specific case it may be best to at least lay out what you want to accomplish. If there's a UI pencil sketch it out. If there are interactions, like for a game, define the basic rules. Think about and maybe prototype some of your data models. As a single developer you can go a long way without a formal design, but when you start bringing people in, having a clear base architecture and some design guidelines are a good idea. As is reviewing contributed code.

Answer 2

As @Tracker1 already mentioned it depends.

The most important thing is managing expectations. Let me explain...

In a standard software project you follow some kind of a software life-cycle process. The main steps or phases are: requirements gathering, planning, development, maintenance and obsoleting.

In all of these steps there are stake-holders involved and it is their expectations that determine what you must do and how detailed and to what extend you have to document each step in the process and which steps are needed.

That includes, what you call specifications, but what is more commonly know as requirements. From the requirements follow the architecture and the design of the software.

It is important to find out the expectations of your stake-holders. These are the people that are going to use the software; that are going to pay for the development of the software; that will have to market and sell the software; QA (Quality Assurance) will be interested in safety and regulatory aspects of your software; the IT department will be interested in what hardware, software packages and development environment you would like to use, etc.

Out of these expectations should come a 'contract' that records the requirements and how to verify that the requirements have been met. This can range from a simple, one-page document to a large number of lengthy documents nailing down every possible detail.

This 'contract' is very important to prevent discussions and arguments at a later stage. It lists what is included and, very important, what is not included and what is required for the project to succeed. It also lists the responsibilities of each party involved. It should also include a time-frame and a budget (not only money but also resources).

Where I work, we make medical devices containing medical software, so we have very strict rules around what we must do and what we must document.

For instance, if we want to sell our products in the U.S., we have to comply with IEC 652304. We are audited by the FDA every few years to ensure that we actually do what we say we do ;-)