Should I use future or present tense when writing a design spec document?

Question

I'm writing a Design Specification Document for a college project and wondering about the tense I should use. The development on the project has not yet started, I'm just writing the UI design section.

Should I use:

This app is built around a two column layout, with a header element.

or

This app will be built around a two column layout, with a header element.

I will obviously continue whatever tense is best throughout the document.

Edit to clarify what I'm actualy writing

The course module discriptor says this:

A detailed ‘design specification’ based on the requirements specification. The completed design specification should be comprehensive and should allow a third party to use your design specification as the basis for implementation. It therefore should be clear, concise and detailed. It may contain: a navigation map to clearly show how you propose how to link various pages or screens; a series of detailed storyboards to illustrate page layout, colour schemes, typography (fonts, sizes, styling, alignment), use of media elements (eg icons, graphics, sound, video, animation) or interaction styles. Justification of design decisions should also be present.

Answer 1

It depends on what you're writing.

If you're writing requirements, then the answer is "neither". Another question here on Software Engineering addresses the use of "shall" and "must" when writing requirements. The guidance that I use at work is that "shall" is used to denote any requirements that must be met for the software to be acceptable to the customer, "should" marks off desired characteristics, "may" is used to identify anything that is optional, and "will" is anything that can be relied upon after the mandatory and any desired or optional characteristics are implemented. If you're not writing your requirements as statements, but using use cases or user stories, you'll want to follow the conventions of that format.

If you're writing about software that already exists, then you should be using the present tense. The software already exists, so it "is" something or "does" something.

If you're trying to define requirements and document a design approach at the same time, I would recommend not doing that and understanding the value of separating what functions the software must expose and the non-functional attributes of the software versus documenting how the software is decomposed or how to use the software. Separation of requirements, technical design, and usage (user's manuals) is very important.

---

To address your specific needs, I think the best thing to do would be is to ask your course instructor or someone else who understands what they are looking for. In my experiences, this type of document doesn't exist in any form of modern software development, so asking professional software engineers how to produce a document that is acceptable to your particular customer (in this case, your professor or grader) won't get you the best answers, especially since I don't think that the answer of "don't do this, it's not good practice, look at your development methodology and approach instead" will get you very far in the course.

A detailed ‘design specification’ based on the requirements specification. The completed design specification should be comprehensive and should allow a third party to use your design specification as the basis for implementation. It therefore should be clear, concise and detailed. It may contain: a navigation map to clearly show how you propose how to link various pages or screens; a series of detailed storyboards to illustrate page layout, colour schemes, typography (fonts, sizes, styling, alignment), use of media elements (eg icons, graphics, sound, video, animation) or interaction styles. Justification of design decisions should also be present.

The requirements specification is the basis for implementing the software, either by an internal or external team. It should not only have your functional characteristics, but design constraints, performance and other quality attributes, user characteristics, required interfaces, and so on. The requirements specification is the agreement between the customer and software supplier.

What you're being told to put into the document is indeed design information. However, it's consistent with "big design up front" approaches to software development where you don't write code until you "finished" your design. However, I'm not aware of very many organizations that embrace this approach.

Answer 2

Take into account whether your document will be read after the software is finished!

If you are writing a proposal which describes what you want to build, then future tense is Okay.

If you want to write a design documentation which will be maintained during the lifetime of your software, then future tense does not make sense and you should use present tense. After all, the document will describe, how your software is designed.

Answer 3

It doesn't matter

It's the content of the spec which is important, not the presentation - and "presentation" includes things like language. The exception here is if the presentation is so bad readers are significantly hampered in their understanding of the content, but present vs future tense isn't going to cause that kind of problem.

Answer 4

Consistency is probably the overriding concern.

For the sake of accuracy, if the documentation pertains to an existing system, possibly one being enhanced, present tense. If the system doesn't exist yet, then future tense, since you are describing something that will happen (hopefully), but hasn't yet.

One thing to consider is that these documents often lead to generation of some of the test cases. In that sense it is better to use future tense, which will then be confirmed in testing. Every "will" or "shall" in the requirements is something that can be tested and confirmed. "does" or "is" implies prior completion and therefore something that does not need to be tested.

Edit, for those who dislike the consistency perspective:

In a development world moving further and further away from rigorous design, requirements and test documents, the consistency and readability of the document are important. And since these documents are less likely to be the sole reference for completion/correctness, the choice between present and future tense is much less important.

For a project which will still a use rigorous documentation process, precision and accuracy of wording (and the consistent application thereof) are critical.