Skip to content

Latest commit

 

History

History
86 lines (57 loc) · 5.04 KB

documentation.md

File metadata and controls

86 lines (57 loc) · 5.04 KB
Raw

Reading & Writing Documentation

Projected Time

About 2 hours

  • 15 minutes for video walkthrough of slides
  • 15 minutes for "Python Basics: Documentation" (video)
  • 10 minutes for "How to Find and Read API Documentation" (video)
  • 10 minutes for "15 Technical Writing Tips" (video)
  • 20 minutes for Group Practice
  • 30 minutes for Independent Practice
  • 15 minutes for Check for Understanding

Prerequisites

Motivation

Software engineers frequently reference a language's or a framework's documentation to understand how to use some part of that technology. It's therefore important to know how documentation is intended to help you, and also how to read it effectively and efficiently.

You will someday want to write documentation for a project you're working on in order to tell or show others how to use the project.

This is such an important topic in software development that many IDE companies provide languages specific extensions to help incorporate and standardize documentation in your code. For example Apple provides this support for Swift in Xcode https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/SymbolDocumentation.html. For JavaScript the Mozilla organization (originally Netscape) created the industry standard JSDoc https://en.wikipedia.org/wiki/JSDoc supported by many IDEs including Microsoft's VSCode.

Objectives

Participants will be able to:

  • Add useful comments to their code
  • Read documentation for the purpose of extracting specific information
  • Write useful, easy-to-follow documentation

Specific Things to Learn

  • Inline comments in HTML, CSS and JavaScript
  • How to read documentation
  • Best practices for writing documentation

Lesson

Common Mistakes / Misconceptions

  • Make sure your comments will make sense to someone with little context for what you were trying to do at the time you wrote the code. This could be a teammate or even your future self!

  • Comments should document the present and occasionally the future, but they should not be used to describe history. That's what version control is for (we'll learn about version control soon).

  • Don't use bad words in comments.

  • "I'll just add comments to as much of my code as possible so there will be no confusion later." This is actually not a good practice. Your variable names and function names should be so descriptive that comments would be redundant. Use comments only to explain things that are not easily apparent by reading the code.

Demonstration

Via instructor-led Group Practice.

Group Practice

Look at this JavaScript code snippet together and talk through it line-by-line. Change some of the variable names and function names to make them more descriptive. Add/remove comments where appropriate.

Independent Practice

  1. Find the JavaScript documentation online.

  2. Locate the entry for the .concat() array method. What does it do? Open a new file in REPL.it and use the .concat() method correctly on an example of your choosing.

  3. Locate the entry for the .fill() array method. What does it do? Open a new file in REPL.it and use the .fill() method correctly on an example of your choosing.

  4. Locate the entry for the .reverse() array method. What does it do? Open a new file in REPL.it and use the .reverse() method correctly on an example of your choosing.

Challenge

Locate the entry for a string method of your choice. What does it do? Open a new file in REPL.it and use the method correctly on an example you made up.

Instructor asks for a volunteer to come up to the board and write out a proper implementation of one of the array methods studied during the Independent Practice. Classmates can assist if necessary. Anyone who discovered more methods during the Challenge section may also share those with the class.

Check for Understanding

  • Why is it important to document your code?
  • What should comments do?
  • What are the two types of comments in JavaScript? What is it used for?
  • What is Markdown?
  • Find an example of a github project with good documentation or an API. Explain why it's good documentation or not.
  • What can be improved?

Supplemental Materials