Hacker News new | past | comments | ask | show | jobs | submit login

I'm really impressed with the readme file in this repository. Its a master class in effective documentation. Just look at the structure:

- 1-2 sentence summary of the project

- History (why we built this and didn't just use existing tools)

- What we've built, including what it does and how it compares to other tools (rsync in this case).

- How to install and use it

And the whole thing is full of images and animations showing the tool in action, and explaining enough of its internals.

I consider myself good at documentation, but I'm taking notes. This is excellent.




This is how I strive to document things. Focus primarily on what the tool is used for and why, not trying to define what it is.


Also for commit messages - why the change is made, not what it is.


The documentation in the code itself is pretty great as well:

https://github.com/google/cdc-file-transfer/blob/main/fastcd...


It’s always amazing to me how little emphasis people give to INTENT on their repo.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: