UTD EPICS: End-of-Semester Documentation Checklist (Fall 2025)

As the Fall 2025 semester draws to a close, it's crucial to ensure your UTDallas EPICS projects are well-documented and easily maintainable for future teams. This comprehensive guide outlines the essential documentation requirements to meet for a successful end-of-semester review. Meeting these requirements ensures the continuity and usability of your projects. Failure to comply with these guidelines may result in a reduction in your final project grade or an incomplete until all necessary information is provided.

One effective way to manage these tasks is by leveraging GitHub issues. You can create individual issues for each requirement and track your progress. For example, you can create a task list like this to automatically check the box when issue 3 is closed:

- [ ] #3 Database Files

This article will cover the necessary project structure, files, and documentation components to ensure your project is well-prepared for the end of the semester. Make sure to carefully follow the guidelines below to ensure your project meets all requirements.

Project Structure and Files

By the final report's due date, your project's main branch must meet the following requirements. These structural guidelines ensure that all necessary files are organized and accessible for future development.

• Up-to-date Code: The most current versions of both frontend and backend code should be included.
• Database Files: Proper database setup is essential for project continuity. Here’s what you need:
  • Docker (if applicable): A docker-compose.yml file should be at the top level for project database management. This ensures that the database can be easily spun up in a consistent environment.
  • Database Schema: A clear schema definition is crucial for understanding the database structure.
    • Prisma: If using Prisma, the schema.prisma file should be located in a top-level prisma folder. Prisma’s schema provides a human-readable and machine-friendly way to define your database structure.
    • Other Databases: For other databases, include a file with a descriptive name (e.g., schema.sql) that can be used to create your database schema. This file should contain all the necessary SQL commands or instructions to set up the database.
• .env.example File: This file should contain non-sensitive environment variables such as the Auth0 Issuer and development database URL. Sensitive variables should be replaced with example data (e.g., CLIENT_SECRET='EXAMPLE_CLIENT_SECRET') to indicate which environment variables are required. This helps future teams understand the necessary configurations without exposing sensitive information.
• Figma Design Files: Include all Figma design files in a top-level folder named figma. This allows future teams to understand the project's visual design and make necessary updates or improvements.
• Scripts Folder: Any migration scripts, development scripts, or other utility scripts should be placed in a top-level scripts folder. If the project has separate frontend and backend folders, the scripts folder should reside in the backend folder. This keeps the main project directory clean and organized.
• Additional Files: Any other important files, such as documentation or notes, should be placed in appropriately named folders like docs, documentation, or notes. This ensures that all project-related materials are easily accessible.

Adhering to this structure makes it easier for others to understand and contribute to your project. Make sure that all of the mentioned files are included and properly organized in your project repository. Proper file organization can greatly enhance the maintainability and accessibility of your project for future teams and collaborators.

Comprehensive Documentation: A README.md Guide

A well-crafted README.md file is the cornerstone of project documentation. It serves as the first point of contact for anyone interacting with your project, providing essential information at a glance. Your README.md file should be located at the top level of your project repository and include the following sections:

• Conceptual Overview: Begin with a clear explanation of the project’s purpose and goals. What problem does it solve, and what is it intended to accomplish? This section should provide a broad description of the different user roles and their interactions with the system. For example, if you’re building a system for a library, you might describe the roles of librarians, patrons, and administrators and how each interacts with the system.
• Functional Requirements: Break down the application’s discrete operations page by page. What specific tasks should the application be capable of performing? This section should be detailed and comprehensive, covering all the key functionalities. For example, a functional requirement might be