Vision Document Guidelines

This document should not to exceed 8 pages, but will probably be more than 4. The document should be concise and formal. There are other artifacts that outline many of the specifics that one might feel inclined to mention in a Vision Document, but this should avoided. Avoid adding more than a summary or quick mention of a few of the most important items that overlap with areas from other artifacts, an only if they fit well in the Vision Document. Keep opinion and overtly personal touches out of the formal documentation except where explicitly required.

As a general rule, avoid unneeded documentation. There are paragraph/line requirements below; do not add fluff for the sake of fluff. If there is not enough real information, it is better to leave a section out than to fill it with triviality. Before leaving a section blank 1) think harder because you are probably missing something or are being a bit lazy 2) be able to explain clearly and concisely why said sections are not there or are smaller than expected. Sections should not be larger than the provided paragraph/line restrictions. Any excess should be cleaned up or trimmed and linked to another appropriate artifact. The Vision Document should never be the only document, but it should be the first thing external people read when they just want to get an idea of the project; it should cover the bases, but not be an onerous read.

Note that a paragraph means 5-8 sentences. If a paragraph has fewer sentences, it may be a sign to cut up run-on sentences or make sure the paragraph is actually saying something worthwhile.

  • Title page
  • Revision history
    • Provide who, when and a sentence or two on what changes were made each time the document is changed (and maybe why). Optionally, a version number can be included which has the advantage of something that one can reference (i.e. "Version 0.15 of the Vision Document said [blah].")
  • TOC
  • Introduction
    • The goal is to give an idea of what the project is and lightly touch upon the rest of the content found within.
    • Provide a brief description of the origins of the project (no more than two sentences). Give a brief description of the origins of the project name (no more than two sentences).
    • An introduction should give an overview of the issues at hand and some idea of scope and approach to providing a solution.
  • Requirements
    • Problem Statement
      • The goal is to provide a succinct means to verbally describe the project.
      • The IEEE Vision Document template included a table with blanks roughly of the form: 
        The problem of ______ affects __________ the impact of which is _________. A successful solution would be _______________.
      • This should be a two-liner that one could give at a meeting in response to off-handed questions about the project.
    • Position Statement
      • The goal is to identify the target audience, give minimal context for the project, describe what it does, highlight its main beneficial qualities, and contrast it with the nearest comparable alternative.
      • A similar template can be followed for the Position Statement, although this can be more difficult: 
        For _________ Who ___________. _[your product]_ is a ____________ that _______________ unlike ________________. Our product _______________.
    • Background
      • The goal is to provide a history of the project, its precedent and its requirements.
      • Record any history of discussion of this project or a description of how it was decided that such a product was needed. Focus on traceability of when/how the project became relevant in the current context and identify any stakeholder involvement before it became an actual project (who said things that mattered to it becoming a project, even if they are not involved after the fact). Identify precedent and how this project or related issues came about, when and because of whom. This should not exceed 3 paragraphs.
    • Context
      • The goal is to describe how this project fits in and to indicate what else has been tried.
      • Describe in more detail the problems or situation that make this project relevant. No more than three paragraphs.
      • Describe related projects or what was done to address the above before this project. No more than two paragraphs for each; a minimum of one related project, no more than three. Always cover what was done before, even if it is to say that nothing could be done.
      • Describe any alternate approaches that have been considered and/or discarded and provide reasons why. Pro/con lists are effective. Include no more than 3 paragraphs and possibly a table. If the discussion is more extensive, it should link to other artifacts (or even wiki pages/other external artifacts on the matter)
  • Vision
    • The goal is to describe solutions that will be provided by this project.
    • Describe how this project will provide a solution given the above context. The solution may identify people, technology, methodologies or something else entirely (or some combination). No more than 3 paragraphs.
      • Include up to one paragraph (but it can be as small as a couple sentences of one paragraph) detailing the long term goals of the project. This is not a place to put requirements or technical solutions, just describe the project goals.
    • Include a table of major features (3-5, possibly broken down to some sub-features if there aren't many... but more than a dozen is excessive), their priority and risk, and when they are targeted for completion. As this is mostly about ordering, the targeting for completion often uses Milestones as a measure, but may be tied to real times in the case of deadlines and such. This is not to replace requirements specifications or other documents, it is to provide priority/risk/planning information to those users who will not be looking at other documentation beyond the Vision Document, and to give them a concrete idea of the Scope.
    • You may optionally describe future release targets/versions, but don't spend more than a paragraph.
  • Scope
    • The goal is to give boundaries to the project and to track changes on those boundaries.
    • Describe the project in terms of boundaries and areas. Future suggestions should be checked against this scope and discarded if they are out of scope. Keep in mind that in a fluid environment the scope can change, usually because someone wants something that is out of scope. Keep this section to within 4 paragraphs, and only so long because identifying boundaries for future defense against feature creep can be tricky.
    • Identify any limitations or expected exclusions in one or two paragraphs. As suggested in some of the references, this is where people will argue, so it is important that this section help elicit arguments early.
    • Create an In/Out table to identify any exclusions or additions to the project over its course. Do not include the initial baseline features included above or those in the initial requirements specification, only those that are added down the road. A date should be included with any addition along with a link to where the addition or exclusion is discussed (it should not be in the Vision Document bloating it). This table identifies changes to the scope by recording them throughout the project.
  • Environment
    • The goal is to give an overview of the expected development environment, technically, politically or otherwise.
    • Outline any technology policies regarding development environments, server usage/restrictions or coding practices to be used, particularly if they are organization standards/policies. Provide a bullet point list that links to external policy if it is available.
    • Any elements that are not linkable should be described loosely in 1 or 2 paragraphs, highlighting who dictated these elements and when (and why, if available).
    • From a technical standpoint, indicate the preferred development environment, deployment environment and programming language. At the very least this will provide a baseline to consider all other options from. This is not always available, but include it when it is, otherwise indicate that it is not (and why).
  • Stakeholder Reference
    • The goal is to identify Stakeholders and their primary characteristics.
    • Here we will specify Stakeholders groups, but also potentially individual Stakeholders (particularly those like project champions). If this is not available early in a project, at least this is a place to put a reminder that this is important.
    • Create a table for Stakeholder Profiles with the following columns:
      • Stakeholder Name (be it group/class/individual)
      • Attitude
      • Major interests
      • Major reservations/limitations
    • Fill this table out as succinctly as possible, and indicate the difference between an unknown value in the table, and when there isn't one to be had.
    • The classification of end-users here is very helpful.
      • Mention Accessibility issues and identify groups with that need as a first-class stakeholder group. It is important to spotlight this in the Vision Document as it is easy to overlook. Also identify if certain accessibility needs will not be addressed and why. This is a touchy subject, so be considerate.
  • References
    • Identify any papers, web pages, previous documents used in creating your Vision Document.

References

I know, these aren't in a proper format. We may want to clarify reference formats elsewhere in the Documentation guidelines (and then I could go apply that)

Attachments