Writing guidelines for this course. Check these items before & also after drafting a document.

    1. Focus Your Topic.
        Do not write about your hopes and dreams. Write about the matter at hand.
        Know who your readers are and write for this intended audience.
    2. Outline.
        Create the document outline, including headings and perhaps subheadings, to organize the document before you write.
        In a previous team course each team had a major heading, each team member has a subheading, and each team member should organize that subsection using sub-subheadings. The details of this section-subsection organization varies according to the purpose of the project and assignment.
    3. Establish Context for Your Readers.
        Warm up your readers. Avoid the common error of launching into low level technical detail in the first paragraph. Readers need to know the overall context of how your proposal or specification fits into the context of the system being proposed. Introduce how your part fits into the whole, and then describe your part in appropriate detail.
    4. Put Some Meat on the Bones.
        You need to say something concrete. Do not write a proposal, a specification, or a manual that is vague. If you will hand a specification off to someone who will perform the next stage of work, your specification should contain enough concrete information so that the next person will get a clear idea of what to do next. You do not need to get into a level of detail that the readers do not need, and you should never bloat the document with useless verbiage. Strive to be concrete in your writing.
        Pay attention to minimum page count requirements when I give them.
    5. Illustrate.
        One picture is worth a thousand words.
        Capture your key illustrations, then write text that describes the structure and dynamics of the illustrations.
        Use good illustrations to guide your writing.
        Use Adobe Illustrator or Google draw to create illustrations that you then import into your Word document.
    4. Write an initial draft.
        Over generate the first draft. Get your ideas onto paper, and then tune the focus and presentation.
        Use complete sentences. A complete sentence contains a subject and a verb at a minimum.
        Use active sentences. For example, prefer: "The students love the software engineering course." Do not prefer: "The course was loved (by the students)."
    5. Edit.
        Use Word comments and change tracking to record suggestions and changes.
        Do not use long, run-on sentences.
        Use spell checking and possibly grammar checking before handing a document to someone else.
        Do not use contractions such as "don't" in a technical document.
        Use capitalization consistently. All product names should be in upper case. (Added 2/15/2015)
        Supply references, particularly URLs for products. Place them in your text or in footnotes as they fit. (Added 2/15/2015)
        Edit down to concise prose.
    6. Use peer review.
        Ask a peer to review your writing and make suggestions about form or clarifications.
        In our class we will perform in-team peer review before turning in assignments.
        Use peer suggestions that you feel are appropriate.
    7. Turn in your writing assignments using a mechanism that I will specify.

General classes of documents for software engineering courses (ignore for other courses):

    A requirements specification states what the customer wants or needs.

    A functional specification states what user-level functionality a customer will see.

    A high-level design specification uses Unified Modeling Language diagrams (UML) or other illustration techniques, along with prose, to give a block-level, outline overview of the design.

    A detailed design gives details of the low-level code interfaces, network message formats, and data formats. It may also use UML. It may use pseudo-code or a rapid prototype.

    A test plan details how to test the system.

    A user's manual documents the software system as the user will use it. It is closely related to the first two specification types above.