Chapter 4 - Git Best Practices

Effective Documentation

Proper documentation is key to the longevity and maintainability of software. You want to make sure if you abrubtly leave a project at any point, anyone else can pick it up without talking to you at all.

  • READMEs: Their Role and Key Elements to Include:
    • A README is often the first item a visitor will see when visiting your repository. It should include a project title, description, installation instructions, usage, contributing guidelines, license information, and contact information for the maintainers.
    • Use the README to provide a high-level overview of the project and how all the pieces fit together. Read more…
  • Wiki: Using a Project’s Wiki for Extensive Documentation:
    • For more detailed documentation, consider using the project’s wiki. It’s a great place for tutorials, examples, design notes, or other detailed information that users and contributors may need. Read more…
  • Code Comments: Inline Documentation for Code Clarity:
    • Well-placed comments within the code can clarify complex algorithms, decision-making, or reasons for significant changes.
    • Use comments to explain the why, not the what — the code speaks for itself on the latter.

🧠 Knowledge Check

Answer the questions below to test your knowledge!

Q1: Which of the following should NOT typically be included in a README file?

Q2: True or False: Code comments should explain what the code is doing line by line to ensure full clarity.

Q3: A project's __________ is the best place to store tutorials, extended documentation, and design notes.

Q4: When documenting your code, what should you aim to explain?

Q5: You're wrapping up your work on a team project and may be leaving soon. You want to ensure others can continue where you left off. What combination of documentation should you focus on?

References

Expand 1. Jamiebuilds. “Jamiebuilds/Documentation-Handbook: How to Write High-Quality Friendly Documentation That People Want to Read.” GitHub, github.com/jamiebuilds/documentation-handbook. Accessed 15 Apr. 2024.
2. Maddy. “How to Write the Perfect Documentation for Your GitHub Project.” DEV Community, 11 July 2023, dev.to/maddy/how-to-write-the-perfect-documentation-for-your-github-project-4k38
3. “The Engineer’s Guide to Writing Meaningful Code Comments.” Stepsize CollabGPT: AI Collaboration for Software Teams. Daily Standups and More., stepsize.com/blog/the-engineers-guide-to-writing-code-comments. Accessed 15 Apr. 2024.