Part 4

Learning Goals

By the end of this part, you should be able to:

1. Apply the ACCEU framework to evaluate and create documents that provide a technical overview of software
2. Identify and explain the various purposes and sections of a good README file
3. Create a useful, high-quality README file in accordance with the ACCEU framework and best practices

Learn: Writing Overall Docs and READMEs

Part 4 Slides (pdf)

Practice: Designing READMEs

Coming Soon... still porting this over from the LMS!

Apply: Critiquing a Real README

Overview

In this hands-on activity, you will choose an open-source Java project on GitHub and evaluate the effectiveness of its README as a piece of documentation. Then, you will create a better README — either a replacement for the project you examined or a new README for the login system from the previous part of this module.

The Scenario

Pick one of the open-source Java projects below. You will be critiquing the README of the project you choose.

• JabRef
• Grasscutter
• Mockito

The Challenge

1. Examine the project's README. Try to understand what the project does. If you find it difficult to understand the project, that may itself be evidence of poor documentation!
2. Evaluate the README using this checklist. Identify what the README does well and what could be improved.
3. Choose one of the following options:
   • Option A: Imagine you were assigned to create a new version of the README for the project you selected. Write a new README as a Markdown file (this can be done locally or in a new GitHub repo). Use your earlier critique to guide improvements. This template README from Bane Sullivan may help.
   • Option B: Write a proper README for the login system from the last part of this module. Create the README as a Markdown file (locally or on GitHub). Use the checklist to guide your work.
4. Reflect on your experience:
   • What challenges did you encounter when writing or revising a README?
   • Which ACCEU principles were easiest or hardest to apply?

If you have any questions or run into difficulties, feel free to ask!

Go to Part 5

Optional readings and references:

• "Drupal" reading: https://www.drupal.org/docs/develop/managing-a-drupalorg-theme-module-or-distribution-project/documenting-your-project/readmemd-template"
• "GitHub" reading: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes
• "Guo" reading: https://www.makeareadme.com/
• "Nyakundi" reading: https://www.freecodecamp.org/news/how-to-write-a-good-readme-file/
• "Otieno" reading: https://medium.com/@kc_clintone/the-ultimate-guide-to-writing-a-great-readme-md-for-your-project-3d49c2023357
• "Patel" reading: https://www.dhiwise.com/post/how-to-write-a-readme-that-stands-out-in-best-practices
• "Pritchard" reading: https://github.com/adam-p/markdown-here/wiki/Markdown-Here-Cheatsheet
• "Sullivan" reading: https://github.com/banesullivan/README
• Image of copyright variants, by Shaddim: https://commons.wikimedia.org/wiki/File:Creative_commons_license_spectrum.svg