Lesson Plan: Chapter 16

Connecting to CSTA Standards

GradesConceptSubconceptStandard NumberPractice
6-8Algorithms & ProgrammingProgram Development2-AP-19Communicating 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.

Learning Outcomes/Goals

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.

Differentiated Instruction

Lower level studentsHigher level students
Can complete the documentation as outlined in the chapterCan enhance their documentation by adding comments into each file and can explain their decisions on what to document and how.

Transfer Learning

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/

Vocabulary

  • 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.

Assessment

Students could be assessed on their understanding of the elements of a well-documented repository

FormativeSummative
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.

Quiz Answers

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.

a. True

b. False

More Resources/Materials

Solution Code

The full third Glitch project has the documentation added to the core README.md fileopen in new window.

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.

ExemplaryAdequateNeeds Improvement
The student build a presentation about their presentation from the beginning, including their peripherals, and presents it to a groupThe student a presentation but it lacks one of the elements requiredThe 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.