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.

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.