Supporting Your Code, README vs Wiki and Test Coverage

README vs Wiki

The debate between using README files and Wikis for code documentation is a common one among developers. Joe Zack and Allen Underwood discuss the merits of each, with Joe advocating for README files to be kept alongside the code to ensure they evolve with code changes 1. Allen agrees, emphasizing the convenience of having documentation readily available within the codebase 2. Joe adds that while Wikis can be useful for broader information like meeting notes, README files are crucial for code-specific instructions 3.

I'm a strong fan of information about the code. It should live with the code and iterate with the code.

--- Joe Zack

This approach ensures that documentation remains relevant and accurate as the codebase evolves.

   

Documentation Tips

Effective documentation is essential for maintaining a healthy codebase, and Joe Zack shares practical tips for achieving this. He highlights the importance of updating documentation in tandem with code changes to prevent outdated information 4. Allen echoes this sentiment, suggesting that developers should proactively update README files to reflect any modifications in the code 5.

It's a fantastic way to let other developers help themselves as they're going through things.

--- Allen Underwood

By keeping documentation current, developers can ensure that their work is accessible and understandable to others, fostering collaboration and reducing bottlenecks.