4

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.

  • 3
    Either way is fine. But above all else, be consistent. – GlenH7 Nov 4 '15 at 19:09
  • 2
    If you are getting to this level of technical writing, you may find that the technical writing tag on Writers.SE may be a better set of experts to answer the question. – user40980 Nov 4 '15 at 19:20
  • What does even "around a two column layout mean"? Use active voice rather than passive voice. Who/what does what, why and when. – thepacker Nov 4 '15 at 20:43
  • This is not a requirments document, it is a design document. It states the design that the developer/designer has come up with to satisfy the requirments spec document. There is more than one way to skin a cat (or fulfil all the requirments in the requirments spec), this is just the one I am proposing. – Christy James Nov 4 '15 at 21:15
10

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.

  • I've already completed the requirments spec document. This is the document where I propose my design solution to those requirments. – Christy James Nov 4 '15 at 21:17
  • @ChristyJames Why are you creating a "design specification"? You should be able to produce the code from your requirements specification and then create a design description to capture what your design. Yes, you do need to make some architectural design decisions very early on, perhaps even before writing code. But once a decision has been made by the team, you want to capture the decisions in a software design description, and once a decision has been made, you do what I say: present tense since you're describing what something is. – Thomas Owens Nov 4 '15 at 21:22
  • Well, the reason I'm doing it is because my college wants me to. If it where me, I would have started building and coding a few weeks ago. But in this course, they like us to jump through hoops. – Christy James Nov 4 '15 at 21:25
  • @ChristyJames Then you may want to take this to your professor to determine how you should write this particular document. In the set of software artifacts described by the IEEE, there is no such thing as a "design specification" for software. Although there is such a thing as a design specification, it maps to a software requirements specification. The only design document in the IEEE software realm is the software design description. – Thomas Owens Nov 4 '15 at 21:28
  • 1
    @ChristyJames I've updated my answer with a new section. Unfortunately, the type of document that they are asking for doesn't really exist, at least in any type of industry standard that I'm aware of. And working in defense and aerospace, I've seen my fair share of types of documents and artifacts that needed to be produced and approved over the life of a project. Since there's no industry basis to give a good answer, the only people who can answer are your customers - whoever will be grading the assignment. – Thomas Owens Nov 4 '15 at 21:54
3

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.

2

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.

-2

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.

  • Down-voter care to comment? While these are not mission critical, they are important things to consider if you interested in evaluating the situation. – cdkMoose Nov 4 '15 at 19:50
  • This answer is wrong. Consistency is not the overriding concern, the point of the document is. For a requirements specification (which is used to generate test cases), then terms like "shall", "will", "may", and "should" have to be clearly defined (and there are standard definitions available). But ultimately, you don't write a design specification before the project begins - you write requirements (in some form) first. – Thomas Owens Nov 4 '15 at 19:55
  • Not the down voter, but an obvious problem in using system existence as the criterion for deciding is that at some point the system will transition from "doesn't exist yet" to "existing system," and "for the sake of accuracy" the document will need to be rewritten. Also, it's not unlikely that some parts of the system already exist while others don't, and switching back and forth will make it hard to understand if the document describes the current system or states future requirements. – Caleb Nov 4 '15 at 19:57
  • It depends on how deeply the team is going to get into the process, at a high level, it isn't critical and consistency is more important for the sake of the reader. If they are going to get deep into a rigorous document process, than it does matter for all of the other points I made. Since OP didn't say and this is for a college project, I gave degrees of an answer. To say it is flat out wrong given the vagaries of OPs question is being a little pedantic. – cdkMoose Nov 4 '15 at 19:58
  • @Caleb, that is why I indicate the importance of the test document confirming the hopes and desires of the design document. The test document and its results document the transition to existence. Switching back and forth is actually critical for a large system to differentiate between what does exists and what will exist. If OP cares to be that rigorous, that distinction is critical. And while potentially confusing, that confusion should poitn to the demarcation. – cdkMoose Nov 4 '15 at 20:00

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.