Course Documents Navigation Page
Introduction
This page is a top-level navigation page. It is intended to help you to find the information you'll
need for each section of your individual project documentation. Each successive page in this set
provides you with the information for a specific document that you will deliver during the semester.
It would be a good idea for you to read all of the pages in this set, even if they are not
associated with the actual deliverables for this course, so that you are familiar with the concepts
presented. For example, there are a number of things concerned with testing that are covered on the
test plan and test procedure document pagess; even though you don't have to produce those documents
for your project, you will undoubtedly be responsible for something similar in your jobs. Therefore,
don't skimp on the readings for this class!! Readings are a lot like
comments — everyone says, "I'll come back and do that later...", but it almost never
happens that way; with comments, nearly every time, the crunch hits at the end of the project and
the comments get left out because there isn't time to add them all in at once. However, if you do a
little at a time, working as you go, you will complete everything together by the end of the semester,
including the readings. (......and the comments!)
You are each required to deliver a Software Development Folder (SDF) for your project. The SDFs will
also be periodically audited throughout the semester for grade, and you will submit them as part of
the project at the conclusion of the semester. Since these are individual projects, there are fewer
sections to be completed for the SDF than if this was a group project as in CMSI 401. However, you
will each be doing your own SDF for your own project, so you are each expected to be your own
"project manager" and "book boss" for your project. The items highlighted in
green below are the deliverables for your project during the semester;
the non-highlighted links are work products which you will often see in your industry jobs, but for
which you are NOT responsible during the semester.
Links to Descriptions of Deliverables
Each of the following links takes you to a page that describes the content of each SDL section:
Deliverables
|
There are two main work products for this class. One, of
course, is the working software application you develop. The other is a "notebook"
containing complete documentation of the project. This notebook will contain multiple
sections, with each section corresponding to one of the deliverable documents that are
listed in the links above. In this case, the documents, after they are delivered (turned
in, reviewed/graded, and handed back) will become a section in the project notebook which
documents that facet of the project development process. Simple, huh? So now, when you
hear the terms "deliverable" or "work product" you will know what is meant.
|
 |
Documentation Notes
There are a number of different names that are applied to documentation of this type. The
"project notebook" is the name usually used at LMU; however, in the industrial world,
the usual term is "Software Development File" or "SDF". The "F" is
sometimes said to stand for "Folder". Frequently, since this is a notebook, the
documentation is referred to as a "Software Development Notebook" or "SDN". In
the CMMI world, it is called the "Software Development Library" and has many more sections
in it than you will have. The terms are all synonymous for us, so don't freak out when you see an
inconsistency in the descriptions within these web pages — it's all the same thing!
The CMMI version, "Software Development Library" or "SDL", actually consists of
two sub-categories, the Software Development Folder (SDF) and the Software Engineering Notebook
(SEN). Companies that use CMMI processes keep this documentation in different ways — some
use notebooks, some have things on line in a shared drive folder hierarchy, some may have special
databases set up, and so on. For us, it will be an actual notebook, and we'll usually refer to it
as simply "your notebook" or "your SDF".
Your SDF is encouraged to be an online document, so that it can be kept as part of your configuration
management repository or in a wiki, if you so desire. I realize you all used "paperless"
systems in your CMSI 401 class this year, (prolly GitHub, right?) and it worked well and saved lots
of trees, so let's keep up with the times. Whatever you use, all sections of the notebook for which
you are responsible must be in evidence. If you keep your SDF stuff in your CM stuff, make a separate
directory/folder/wiki/page-set/blog for it.
Old-school Software Development Library Mechanics
 |
Your project notebook (if it is an actual notebook!) will be a loose-leaf style binder,
3-rings, with dividers. These are usually available at the bookstore, or at fine stationery
stores in your neighborhood. It isn't required, but it is sometimes useful to have the kind
of binder that has the "pocket" thingies inside the covers. Also, it is usually
easier if the dividers are the type that you can insert your own labels in, but again this is
personal preference. You may end up needing more than one size notebook over the duration of
the semester. There won't be much in it at first, so it's not really necessary to have a
3-inch notebook with 5 pieces of paper in it. However, as the semester (and the project)
progresses, you may need a larger size to hold all the documents you'll be generating.
Believe it or not, some people still prefer paper over reading the text on a screen. There
is no shame in that philosophy!! If you are one of those who are thus inclined, feel free to
NOT do the online thing. Rest assured all notebooks will be graded equally, regardless of
format. The instructions will all be written from the standpoint of paper copies, so you can
interpret accordingly.
|
By the way, since notebook sections will need to be numbered, I'd suggest using LaTeX for all your
documentation. This tool makes it easy to include section numbers on the pages, and will allow you
to put different sections into different files for easy editing and maintenance, then lets them be
combined in one "build" operation. Flippin' SWEET!
So, what's in the SDF, you may ask?
This is actually easy to answer; just go on to the next page and scroll
down near the bottom of the page. You'll see the entire TOC for an industry standard styled SDF, and
you can use that to structure your documentation accordingly.
The following paragraphs provide more detail about the lessons learned, history, and notes sections,
with respect to what is expected in an SDF. You can read them now, or just skip over them to get to the
bottom of the page, where a handy link is located on the right side, to go to the
next web page in this course documents sequence.
These course document pages are designed to take you through all the sections of an SDF in order;
as you read each page, the "Next Document" link at the bottom of the page will take you to
the next page in the succession, until you visit them all. The link on the final page returns you back
to the start.
Lessons Learned
|
The Lessons Learned section of the SDF, usually just a couple of pages,
provides some information about things that you learned during the project. If you have a really
neat algorithm that you designed, or a particular challenge that you had to solve, or some other
problem or success that you feel is noteworthy, this is the place to put it. This way these things
can be documented. For example, if you felt you didn't scope the project well, and there were parts
that had to be left out, there could be a paragraph explaining what went bad and what you would do
differently. Or, if you were able to re-use a significant portion of code from some prior project,
you would include details about what you did to get the code integrated, along with an estimate of
how much time this process saved you for this semester. In industry, this stuff is usually put into
a database that is reviewed by new project teams when they are just getting started on a new project
so they don't keep making the same mistakes as previous teams. This is known as "not
re-inventing the wheel".
|
 |
History
The History section is a repository for changed notebook sections. If you re-write a portion of a
SDF section, print a new copy, insert the new copy in the SDF section, then stuff the old version
in this History section. It doesn't matter what order the stuffing is done in, the idea is to NOT
throw anything away so that if you want to refer to it there is a record. This has saved my bacon
lots of times, in everything from myself wondering "what did I do", to my boss wanting me
to put it back the way it was, to "Look, I did it that way BECAUSE YOU TOLD ME TO!"
Worthwhile, really...
Notes and Miscellany
The Notes section is a good place to put all other notes, like preliminary drawings of GUI screens,
interface descriptions, paper napkin notes from Denny's, cell phone pix of whiteboard design sessions,
and so forth. These are things which are NOT deliverable, but will come in handy at a later time, so
you don't want to lose the information. Important safety tip: Even though the notes
themselves are not "devliverables", the section is deliverable, and must be included
in whatever form your SDF ends up taking, whether on line, hard copy, or other.
Next Document