{"id":168,"date":"2020-02-13T16:26:35","date_gmt":"2020-02-13T21:26:35","guid":{"rendered":"http:\/\/redmonk.com\/kfitzpatrick\/?p=168"},"modified":"2020-02-14T09:11:53","modified_gmt":"2020-02-14T14:11:53","slug":"docs-roundup-1-2","status":"publish","type":"post","link":"https:\/\/redmonk.com\/kfitzpatrick\/2020\/02\/13\/docs-roundup-1-2\/","title":{"rendered":"Docs Roundup 1.2"},"content":{"rendered":"

Recent docs (and tech comm) items of interest: README files; code comments; medieval tech comm; tech comm and critique; a miscellaneous usage issue illustrated with cake<\/span><\/i><\/p>\n

\"Illustration<\/p>\n

README files<\/span><\/h1>\n

For many of us (especially those of us who <\/span>installed software sometime in the previous century<\/span><\/a>) README files are a familiar form of technical documentation that we encounter as consumers. For those unfamiliar with the role README files play today (especially in public-facing software projects), <\/span>GitHub has a nice definition of README files in its help docs<\/span><\/a>:<\/span><\/p>\n

A README file, along with a <\/span>repository license<\/span><\/a>, <\/span>contribution guidelines<\/span><\/a>, and a <\/span>code of conduct<\/span><\/a>, helps you communicate expectations for and manage contributions to your project.<\/span><\/p>\n

 <\/p>\n

A README is often the first item a visitor will see when visiting your repository. <\/span><\/p><\/blockquote>\n

Looking for resources on creating README files? Check out this <\/span>README template<\/span><\/a> from <\/span>Billie Thompson<\/span><\/a>. You can find more templates and guidance at <\/span>Make a README<\/span><\/a> (many thanks to <\/span>Lisa Wold Eriksen<\/span><\/a> for surfacing this resource). Or <\/span>Nerando A. Johnson<\/span><\/a>\u2019s writeup on <\/span>Writing The Needed ReadMe<\/span><\/a> has a great take on <\/span>why <\/span><\/i>developers should care about this type of documentation (as well as how to get started writing one):<\/span><\/p>\n

So here you are, you have good written code and uploaded it to whatever open source repository you use Github, Gitlab, Bitbucket or even your own hosted repository. You are sure your code works, you have tested it, retested… even tested it on Becky’s machine and refactored it on your machine and sure it works. So the question to the person who looks at you[r] repo is …… HOW THE HELL DOES IT WORK ?????\u00a0<\/span><\/p><\/blockquote>\n

Finally, a nice reminder from Matt Broberg about the purpose of these types of files:<\/span><\/p>\n

\n

OH: it\u2019s a readme, not an entertain me. @kimadeline_m<\/a> #pycascades<\/a> \ud83d\ude02\ud83d\ude02\ud83d\ude02<\/p>\n

— Matthew Broberg is at @mbbroberg@floss.social (@mbbroberg) February 8, 2020<\/a><\/p><\/blockquote>\n