Capstone Project Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Software Projects ======


There are now more Capstone projects with objectives that are entirely software based or incorporate software components. However, software designs have characteristics that can make them different from the hardware-focused projects historically sponsored in BYU Capstone. 

Because of the ability to rapidly prototype changes and the fact that your prototype can actually become the product, the nature of software projects is more iterative than most hardware design projects and follows the process outlined in [[https://byucapstone.byu.edu/design-decisions.pdf#page=58|Figure 6-3 of Design Decisions]] more closely than the traditional waterfall project management procedure associated with the Capstone hardware development process. However, because of the fixed schedule and resources allocated to your project, appropriate goal targets combined with agile management are essential to ensure that your efforts are appropriately mapped to achieve a successful outcome. 

You should use software to manage software. Appropriate use of [[https://gitlab.com|GitLab]], [[https://github.com|GitHub]] or another repository management system will enable you to keep track of different software components and successfully combine the efforts of your team members.

===== Artifacts =====


Throughout the software development process, you will need to show that your product does what it is supposed to do, does not do what it is not supposed to do, and can be updated, refined, and deployed by future engineers. In this way, the principles of desirability and transferability apply to these types of projects. //**Generally, software projects will not produce the diversity of artifacts of hardware projects, but the artifacts they produce will be updated much more frequently as coding progresses.**// Do not expect that a one-to-one mapping of artifacts recommended for hardware projects will be used for a software project. Major artifacts that describe the software product deliverables are the following:

====Desirability ====

Software Requirements Specification ([[https://en.wikipedia.org/wiki/Software_requirements_specification|SRS]] from Wikipedia) 
  * A  [[https://byu.app.box.com/file/863679343603|Word template]] for the IEEE SRS is available in the Class Documents/Templates folder on Box. This will serve as the primary requirements documentation for your software projects.
  * This document will go through many versions as you progress through your project.
  * An [[http://itest.sourceforge.net/documentation/developer/Software_Requirements_Specification-iTest.pdf|IEEE example]] of an SRS is available online. This can provide a sense of the types of content that is desirable for each section.
  * The requirements should be unambiguous in the sense that a third-party could verify if your design meets/does not meet them.
  * An [[https://byu.app.box.com/file/863664655524|example of a Capstone team's SRS]] is available in the Class Documents/Examples folder on Box.

Market Response (from market about the desirability of your product)
  * Remember that the design team is not the market, so outside feedback is absolutely necessary to judge the success of the design.
  * Release Notes/Bug Testing Report (showing appropriate code coverage and successful test passing). These are critical to evaluate the progress your team is making and allows future developers to know what needs to be addressed.

==== Transferability ====

User Manual – The user manual provides complete instructions for the use of your software product. It should explain to a novice user (who is familiar with software in general) how to set up and use the software. It should be in plain English, and a good test is to have someone unfamiliar with your project step through the User Manual.

Overall Code Documentation - [[https://www.sphinx-doc.org/en/master/|Sphinx]] or [[https://doxygen.nl/|Doxygen]] may be helpful in your documentation process.  [[https://jupyter.org/|Jupyter]] notebooks can also provide great visual documentation.

Software bill of materials - A Software Bill of Materials is a list of all software components, the supplier, version numbers, open source licenses, and dependencies. The ([[https://www.ntia.gov/SBOM|SBOM]] page from NTIA contains exhaustive information about SBOMs. Capstone teams need not go into as much depth as the NTIA discusses. The goal of your SBOM is to ensure transferability of your software. An example SBOM from a previous Capstone team can be found in the Class Documents > Examples > Software Artifacts on Box. A template is not provided so that you can format your SBOM according to the needs of your project.

Repository – Ensure that your code repository is kept clean and up to date. Access to your repository should be given to your sponsor at the conclusion of the project. At the end of the project you will need to download and copy your repository to the BYU BOX site, too.

Software architecture/navigation artifact – Flowcharts, state machines, block diagrams, UML diagrams, and other visual aids can assist in explaining how your code works at a high level. Create these in high-resolution form (LucidChart, PPT, Adobe Illustrator, etc) so they are clear in your presentations and reports.

Appropriately commented code – Use comments in your code to explain the intention of specific blocks of code that may not be obvious to the uninitiated. Use descriptive variable names rather than generic variable names.

===== Software Development Mapped to Capstone Stages =====

For projects that are entirely or heavily software, some of the explanations for the Capstone development stages may not translate cleanly into the language of software designers. A mapping of the stages of project development for a software project in Capstone may look more like the following, with multiple iterations of the software happening between stages (1.0 constitutes a major or public release): 

**Opportunity Development -> Software Requirements Specification V 0.8; Software V 0.1**

In this stage, the team works with the sponsor and market (which is likely to be your sponsor) to determine the high-level requirements (“Key Success Measures” in Capstone-speak). Risks are assessed and thought is given to testability. Software “prototypes” are often written to determine feasibility. These requirements are clearly defined and documented in the SRS.

Sections 1 (all), 2.1, 2.2, 2.4, 2.5, 3 (all), 4 (all), 5(all), and 6 are all addressed in the SRS. Some explanations will be very rudimentary at this point. Requirements will be more specific. 

**Concept Development -> Software Requirements Specification V 1.0; Software backend V 0.3 with GUI V 0.1**

The architecture is presented visually, with clear diagrams specifying modules and interfaces. Evidence from software prototypes is presented to demonstrate feasibility of the concept. Videos of working code may be included in the review.

A test plan is also included to demonstrate testability of the software components as well as the complete software package, when completed.

A Software Bill of Materials should be included as part of your Concept Review.

**Architecture Development -> Software Requirements Specification V 1.1; Software backend V 0.5 with GUI V 0.5**

The software architecture is fully specified. Modularity, budget constraints (both money and time), testability, and robustness are all considered, justified, and documented. 

Programming languages are specified based on what is best for the project and what meets the needs of the sponsor to ensure transferability. 

Architecture diagrams (block diagrams, UML diagrams, flowcharts, etc) are developed that illustrate your design, and these include clear interfaces between modules. Details of the design are all clearly specified, including data flows with external modules. If your project includes a GUI, wireframe diagrams (software packages like Figma, InVision, Adobe XD, can make this easy) should be used to provide clear mockups of the GUI design.

A high-level test plan is included demonstrating thought has been given to testability of the software (including automated testing as appropriate).

A formal schedule is presented that includes not only Capstone “milestones” (due dates), but also key development milestones specific to the project that must be met to ensure the development cycle stays on track.

Additions and modifications are made to the SRS as needed. All sections of the SRS have content.

A Software Bill of Materials includes all software, including version numbers, used and provides details to recreate the development environment. 

**Subsystem Engineering -> Software Requirements Specification V 1.5; Software backend V 0.9 with GUI V 0.9**

Code is developed according to the design specified in the architecture review. Code is well documented, including in-line comments that explain what is being done in functional blocks of code. Variable names should be helpful in explaining what is happening in the code block.  

A Software Bill of Materials lists all software packages used, including version numbers. Documentation for recreating the development environment is maintained. 

Project management is mandatory at this stage. Deliverable dates and team member responsibilities are clear and easily accessible by all team members. Dependencies are recognized and tracked. (See [[project-wiki:tools:software_resources|Software Resources]] for tools you might employ to make this easier).

Test plans are written and executed, and results are documented. This may take the form of a Jira board, Github bug reporting, or whatever works best for your team. 

SRS is updated appropriately. 

**System Refinement -> Software Requirements Specification V 2.0; Software backend V 1.2 with GUI V 1.2**

This stage represents the final aggregation of all components and modules into a single system. The complete software package must be tested again as a system. 

Makefiles are used and documented to automate the development environment. 

SRS is complete and accurate. 

Software Bill of Materials is complete and accurate. 

Test plans are specific and address areas of potential failure. In the testing, attempts are made to break the code. For example, if given corrupt input, does your software return an appropriate error message, or does it fail? Automated tests are used where it makes sense to automate.

All details to recreate development environment and run software are included in the final report. Output is clear. Obvious thought has been given to user experience. 

===== Software Testing =====

Software testing is a significant element of software product design and is typically categorized into functional and non-functional testing. The major stages of functional testing include: unit testing, integration testing, system/regression testing, and acceptance testing. Non-functional testing may include: security, performance, useability, and compatibility testing. It is unrealistic to expect that a Capstone team will be able to adequately perform complete software testing on your design. However, the following minimum testing should be documented and completed:
  - Unit testing – testing the individual components, functions, or modules. Automating these tests is often helpful and can save time overall. This is the type of testing that should be done during OD, CD, and SSE.
  - Integration testing – verification that the modules, when integrated, still function correctly. This may need to be done during CD and must be done during SSE.
  - System/Regression testing – verification that the entire system works together as a whole. Attempts should be made to break the code to prove it is robust enough to handle unexpected variations in the run-time experience. System testing is done during SSE and SR.
  - Acceptance testing – your sponsor should verify that your software design meets the requirements, which should be an accurate reflection of their needs. Documenting a successful acceptance test is evidence of the success of your project.
  - Non-functional testing – Unless required for your project, this is likely outside the scope of Capstone.
Capstone Project Wiki

User Tools

Site Tools

Page Tools
