Lesson Plan: Chapter 16
Connecting to CSTA Standards
|6-8||Algorithms & Programming||Program Development||2-AP-19||Communicating About Computing: 7.2|
Document programs in order to make them easier to follow, test, and debug.
Documentation allows creators and others to more easily use and understand a program. Students should provide documentation for end users that explains their artifacts and how they function. For example, students could provide a project overview and clear user instructions. They should also incorporate comments in their product and communicate their process using design documents, flowcharts, and presentations.
This chapter introduces the vital concept of documenting your software. There's no such thing as self-documented software, and there are, conversely, best practices on how to comment code and explain software via good docs.
|Lower level students||Higher level students|
|Can complete the documentation as outlined in the chapter||Can enhance their documentation by adding comments into each file and can explain their decisions on what to document and how.|
Students can visit many different repos of well-known open source projects and compare documentation. Take a look at the React docs, for example, to see an excellent example of interactive docs: https://beta.reactjs.org/
- Code of Conduct: A document outlining the ways that users should interact with each other while using the software governed by the Code of Conduct.
- Docs As Code: A concept that holds that docs should be built with the same code as the codebase described.
- Documentation (docs): The written record that explains all aspects of a given body of code.
- License: The legal document that governs appropriate use of software.
- Open source: In software, this term refers to artifacts that people can modify and share due to its being publicly available.
- README.md file: A file living at the root of a codebase (it can also live elsewhere) that commonly includes an outline explaining the codebase's general structure and purpose.
Students could be assessed on their understanding of the elements of a well-documented repository
|Research excellent examples of documentation and create a list of all the elements needed.||Write a summary of the various ways that some repos are documented, vs others, and compare the issues and questions in comparable repos, to discover whether repos with better documentation have fewer problems reported.|
Q1: It’s important to include a license with your open source software because:
a. It governs how others can use your software
b. It allows you to make money with your software
c. It stops others from copying your software
Q2: Documenting your software project does which of the following?
a. Helps explain the elements of the software
b. Helps users use your software
c. Both of the above
Q3: Commenting your code is essential to help maintain it.
The full third Glitch project has the documentation added to the core README.md file.
Assignment and Rubric: Showcase
Build a Google Slides or Microsoft PowerPoint presentation about your project that mirrors the documentation you wrote. Use it to present the entire project from the beginning, including your flowchart, design sketches, and other decisions. Present it to an audience new to 3D modeling and see if they feel like they could build a world like yours after watching your presentation.
|The student build a presentation about their presentation from the beginning, including their peripherals, and presents it to a group||The student a presentation but it lacks one of the elements required||The student creates only a minimal presentation and/or fails to present it|
*tip: prior to saving as a PDF, select the 'light' mode at the top using the 'sun' icon.