Supplemental Guides

Page Contents

Developer’s Guide

The Developer’s Guide contains information for sponsors or future senior design teams who want to extend the project or integrate it with other systems. This Guide should not duplicate material from your Final Report. Instead, this is an opportunity to focus on aspects of your project that would be of interest to a developer continuing your work, such as when updating the development environment setup and use, or making modifications and extensions to the project. Include all commands required to install development tools and dependencies on a given operating system, run the software from a checkout, and run all tests.

Developers may be unfamiliar with some parts of your application so be certain to not skip any installation steps. Where possible, automating the setup process via a script, makefile, or some other tool is encouraged, and also leaves fewer steps to document in this guide.

Teams should document aspects of the design or implementation that developers might be expected to extend, modify or replace during the lifetime of the software product. In particular, if the project design includes specific interfaces or mechanisms for extension, the Developer’s Guide is a good place to highlight them, possibly with a step-by-step example of a typical extension.

Mention notable directories and files and major classes in your program that users will want to start with when exploring the code. For the most common development use cases, walk a developer through how to do them – this could include how to add a new REST API route or a new table, data model, and associated migrations – and what files are involved. This might also include adding a new page to a web interface.

If there are public library interfaces or REST APIs that are meaningful, show snippets/examples of how to use them here. REST API documentation can be included in the GitHub repo and simply referenced here, especially if code generated, through examples on how to use the various routes – as well as common API conventions – should be included. For instance, a REST API should explain authentication, querying, sorting, and pagination conventions.

Be sure to describe the steps needed to build the application and other artifacts that will be referenced in the Installation Guide. Ideally, build commands should be automatable via script or makefile and not require protracted instructions for how to interact with a particular IDE. All applications probably have some build or packaging steps to document here – these may include compiling programs, packaging static files, or minifying JavaScript.

Installation Guide

When the product is delivered to the sponsor, build, installation and configuration steps will typically be required. Unless otherwise specified by the sponsors, the Installation Guide should describe the process of deploying the system to a production environment rather than a developer setup. Assume that developers or IT operations staff are the target audience. The Installation Guide should also contain instructions for verifying that the system installation is working properly after installation. The Guide should include details about how to configure the system or add the first users to the system (if appropriate). Be sure that the installation does not include test or dummy data. For a web application, provide instructions for installing in a production web server, as opposed to running a development webserver from source from a local checkout. This includes providing guidelines and suggestions to improve the security of a deployment (e.g., running the application exclusively under HTTPS).

The Installation Guide must address the following:

  • Identification of all tasks required for product build and installation, by providing specific examples of commands to run, including installation of all dependencies. Include brief explanations of what’s being done if it might be non-obvious. If the system requires a database, this guide should provide clear instructions for where and how to configure connection parameters. Include all steps to install the application in a production installation, suitable for inclusion in a shell script or entering via a command-line tool, if possible. Automating the install will allow for fewer steps to be documented.
  • A troubleshooting guide that describes the steps that will be taken for common problems that may be encountered during build or installation.
  • A verification plan that describes the means to be used to verify that the project installation is successful. This might include checking program output, sending web requests, and so forth.

User’s Guide

The User’s Guide describes the operation of the software product for one or more classes of end users. This document should describe the user interface and typical use cases, typically covering all the functional requirements for the product.

The User’s Guide should be written as if being read by a target user, explaining what can be done with the application, and how to do it.

  • Start by identifying how the user will start interacting with your software. If needed, explain how to sign-in and profiles.
  • Then describe all the use cases as a series of steps/subtasks, use if-then approach and use diagrams for more complicated tasks.
  • Where possible, annotate screenshots with arrows/annotations and explain basic use cases.

Think about reference manuals you have read and what information a new user needs to learn about the application. Don’t assume that the reader is familiar with the requirements section of your report or that they have prior knowledge of what your application is capable of. Ideally, a reader should be able to understand how to use your application, even if they don’t read any of your other documents.