Why should you document your design?

Documenting a project vision is justified in probably all of development methods and methodologies, like Agile/SCRUM, Waterfall, PRINCE2 or even Kanban. The idea of documenting is simple - we need to know what to develop. When vision of a new concept becomes to be a project, it’s always a good idea to document it. That’s what we are taught on universities, in companies or on trainings. But what are some objective reasons for doing that? Why not just start the project straight from a concept in the head?

Concept is just an idea which has to be developed to become a more detailed vision, taking into account all features.  The main problem is how (and sometimes even why) the vision document should be written? From my experience I can tell that there are three important areas of development for such document:

1. Does it make sense?
2. Evaluate whether the project can be done.
3. Help the project to live.

There are probably more things, like team motivation, looking for investor (pitches, you know)

1. Does it make sense?

There are couple of simple questions which has to be answered “yes”, e.g.:

• Is your project consistent?
• Are designers happy with overall concept and/or crucial details?
• Do you have time and money for it?

2. Evaluate your Vision

After a team is happy with it’s project, it needs to be considered how is it to be done. Find risks and challenges between planned features and current team.

• measure size of project which implies time and people resources
• find about technical problems and define what could be possibly unexpected to stop development
• prioritize features, some may be cut and some even more deeply developed

If there are unsolved problems with crucial features or resources then vision needs some “solvation”. Otherwise it may need salvation in the future :-)

 3. Help the project to live

Your design probably will be alive, it will change in time. Also your team is most probably alive, so it’s very important to not make useless changes emotionally.  This is how your design document will help in production process:

• when you forget how it was supposed to work, you look in to document
• when you argue in team what’s to be done, then written design document is your mediator
• when you want to change something in the project, everyone responsible for design has to agree for a change, which has to be written into the document
• when you want to add new features, you can immediately see whether current vision isn’t too big to be extended
• when you want to cut features because, then you see what could be safely cut from a big picture

so your project can be actually done, after all.

Final tips

Big picture

Apparently having a big picture is the most important thing in there. I recommend using top-down approach. It’s best to start with short project description, then big features and then going into details. Going into details at first could make a proof that project isn’t valuable because it isn’t interesting as a whole project.

People will read it

Try to write understandable text at all costs, even if it seems to be too long. Sometimes it’s better to throw it at other people before trying to explain it to them. It’s important that people understand it the same way you do, because they will argue with it in the future.

Constraints

Take constraints into the account at some point. Obviously for software there are always technical constraints. In onther situations there are client expectations or requirements. Don’t ignore things which cannot be overcame.

Inspirations?

If you want some inspiration find some templates. For Game Design Documents there is a good one which I recommend: Game Design Document Template