![]() ![]() Need some more ideas for an even better README? Stephen Whitmore created Art of README: Learn the art of writing quality READMEs. Jesse Luoto has written a simple yet incredibly handy Readme Best Practices: Best practices for writing a README for your open source project page, as a README.md file, with a default README outline that you can clone directly into any new project, and it's all provided as "free and unencumbered software released into the public domain". ![]() What should be in your README beyond the basics? GitHub can create a README.md file automatically for a new repository and displays it by default, with formatting, in your repo page, so there's little excuse to skip this simple step. If you do nothing else, at least create a README file that provides basic information about your code or project, how to build or invoke it (if executable), and license or copyright details. ![]() Here are some tools and advice to help you get the job done. The answer is to create some documentation for your code, preferably good, comprehensive documentation. Or someone wants to use the code from your repository and keeps submitting issues asking questions about it. Or when the colleague who wrote that code leaves the team and now you're responsible for maintaining it. Creating even the most simple documentation - notes in work tickets, comments in code, a README file - helps us remember what we created, how it works, and why we coded it that way months later after we've written thousands of lines of completely unrelated code. It happens all the time and I've seen it over and over. and now you'll spend the better part of a day relearning the code you wrote in the first place. Hey, I bet you've even written code that, six months later, you forgot how it works. We've all written code that works perfectly fine for us, because we wrote it, but other users need help knowing what it does and how to put it to work. It's no secret that I believe documentation is a crucial element of quality software - and not just because I've spent most of the last 25 years working on end-user and developer documentation. ![]()
0 Comments
Leave a Reply. |
Details
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |