Course Documents Navigation Page


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:


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.

The Software Truck!

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

The original SDL

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".



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