Due:
product website at
23:00 on October 28, 2016
via course dropbox
The Zero-Feature Release (ZFR) milestone consists of a skeletal implementation of your product. The initial implementation must be installable and executable, but running it does not have to do anything except display an initial window, webpage, or whatever your UI displays. This milestone will help you ensure that your toolchain (version control, bug tracking, deployment, etc.) is operational.
Your entire submission will consist of a single URL—the website for your product—submitted via the course dropbox. This is different from, and should be linked from, your team website.
The product website should include information about your product, including how to obtain the current release. If your project is itself a website, then the current release is likely to be a live installation. We don’t care about the format, as long as it is clear how a user can install (if necessary) and use your software, and it is clear how a developer can begin to work on it (often via a link back to the team website). If your project includes an Android application, be sure that the app is available for download and installable. This will allow the staff to install it on an emulator or a new device to ensure that the app fulfills the ZFR requirements.
All information on your website must appear in your version control repository. In particular, it should be possible for someone not on your team to check out a copy of your repository, build according to your instructions, and then work solely from the copy. And this is, in fact, what the staff will do, in order to ensure that all the information is in your repository. You may continue committing to your repository—the staff will check out a version as of the due date, so we will be insulated from subsequent changes to the repository or website.
Like any open-source software, your project will ship with documentation of two types: that for end users, and that for developers. The product homepage should be focused on end users, but developers should be able to use it to find the information that they want, including where to find your repository.
Don’t forget to include a plain-text README file or a Markdown
README.md file in the top-level directory of your distribution and
your repository. At a minimum, it should contain a pointer to your
user and developer documentation.
Your documentation for users should include at least the following information:
A description of your project, such as what it does, what is unique about it, and why a user would want to use it.
How to obtain and install the software. For hosted software such as a website, the installation instructions may be empty. Your instructions need to be both complete and foolproof. Indicate all steps that a user must take to install your system, on each relevant platform (e.g., a departmental Linux home VM or a standard mobile platform). Assume the user is a CSE undergraduate who knows nothing about your platform and toolset. If your project has prerequisites (e.g., tools, libraries, emulators, third-party applications, etc.), your instructions should list all of them and indicate how to install and configure them.
How to run the software (that is, how to start it up). In some cases, the instructions may need to include information such as how to access data sources (e.g., how to create and populate a database), or other customization information.
How to use the software. Assume that your user is familiar with your particular platform (e.g., use of a Web browser, desktop applications, or a mobile phone). Questions you might answer include the following. What is the concept around which the UI or user experience is organized (example: a canvas) and the way in which the user interacts or performs specific actions? Is the software designed by analogy to some other software, or to some process in the real world? Are there modes? What is the workflow?
How to report a bug. This should include not just the mechanics (a pointer to your issue tracker), but also what information is needed. You might want to reference a resource about how to write a good bug report: Oracle, Mozilla, Ximian, Tatham, Raymond.
You might choose to make the product homepage be the same as the user manual, or make them separate, with the homepage linking to the user manual. If the user manual is a separate document, it may be in HTML, PDF, or Markdown. The homepage and other documentation does not have to be visually elaborate or use over-the-top web design, but it must be informative.
Your documentation for developers must include information for someone who wishes to contribute to your project as a developer, to create a customized version, to pick up development where you left off, etc. A CSE undergraduate who knows nothing about your platform and toolset should be able to follow the instructions without confusion or delay. The developer documentation should include at least the following information:
The layout of your directory structure: what the various directories (folders) contain, or where to find important information such as source files, documentation, data files, etc.
How to build the software (e.g., compile it from the original sources). In some cases, such as if you are building a standalone application using an interpreted language, there may not be any build instructions. If so, you should state that explicitly.
How to test the software (e.g., run the test suite). In some cases, the instructions may need to include information such as how to access data sources (e.g., how to create and populate a database), similarly to or in addition to what a user must do. For example if your software is a website or web service, the developer documentation must include everything a programmer must do in order to get a test version of the website up and running your software. You may reference the user documentation to avoid duplication.
How to set up an automated daily (or more frequent) build and test. For your daily build and test, you may wish to use Travis, Jenkins, cron, or similar software. Also describe how you set up your daily build and test system, and how you ensured that any failure output is emailed to your entire team. (Don’t describe how you might have done it or how you plan to do it; actually do it, and describe what you did.) It is a requirement that before the due date, at least one failing daily test result is automatically emailed to the team. This obviously requires that at least some tests already exist. We do not require any successful daily tests yet.
Your instructions should make clear how to control the website to which your files are copied. For example, it is recommended that a developer can create a private release (sometimes called a testing release). That way, you can test your software without breaking the publicly-available version.
How to access the list of outstanding bugs and the list of resolved bugs, and how to resolve a bug. (This can be simply a URL for your issue tracker.) For the ZFR, your bug tracking system need not have a comprehensive list of every last bug and missing feature. However, for this and future assignments, if the course staff runs across a problem while using your software, you will regain some credit if the bug tracking system contains a description of the problem.
All of the tasks (running, compiling, and releasing your software) should work on a CSE Linux home VM. If that is not the case, please talk to the course staff.
The staff needs access to your version control repositories, bug trackers, databases, and the like. We prefer that you give access to the course staff members’ normal CSE and/or Google accounts. If this is impossible, then make a new account that the staff can use to access all of your materials, and tell us the usernames/passwords.
You may want to arrange a “dry run” with your TA beforehand (after doing a flawless one yourself, of course), to ensure that your instructions work.
You can and should reuse the information from previous assignments. For example, part of your user documentation might come from your requirements and UI documents, and part of your developer documentation might come from your design documents. We do not want you to maintain two parallel versions of information; any future revisions of design/developer documents can refer to your user documentation where appropriate. In other words, every relevant piece of information should appear in your repository, but only once, and in a place that is easy for a user or developer to find.
If some details of (for example) your UI are not yet determined, you can leave those out; there is no sense in creating a polished document about things that are likely to change. But many aspects of your project should be settled by now, and you should document all of those. The documentation should reflect the progress your team has made so far, and should be updated with every future release.
Be brief. There is a lot of information to convey, but if you carefully organize your work (and if you have designed simple processes, both for users and developers), then your documents will not be long.
Write your documentation to be useful to a user or developer. The most important thing is that your system have a professional feel (modulo expected incompleteness at intermediate stages of the process, of course).
The user/developer directions should be written so that a careful (but not telepathic) user/developer can follow them.
Your directions must accurately match what the user needs to actually do. However, part of your grade will assess the simplicity of the instructions—the number and complexity of commands that a user or developer must use. Ideally, each task (compilation, testing, deploying) can be accomplished using a single command (a “one-step build”) that invokes a build tool such as Make, Ant, etc.