[HN Gopher] I'd like to review your README
       ___________________________________________________________________
        
       I'd like to review your README
        
       Author : edward
       Score  : 293 points
       Date   : 2021-04-17 06:59 UTC (16 hours ago)
        
 (HTM) web link (liw.fi)
 (TXT) w3m dump (liw.fi)
        
       | einpoklum wrote:
       | Won't this fellow's queue fill up for months once this link is
       | posted here on HN?
        
       | tirrex wrote:
       | It would be great if author points us a few READMEs he likes. So,
       | people can avoid many issues before asking for review.
        
         | hakre wrote:
         | Also the record of readmes and their date when reviewed would
         | be very insightful.
        
         | remoquete wrote:
         | This. Or, you know, some sample pull requests he created.
        
       | witcher wrote:
       | Great initiative! Thank you for doing this, it's definitely nice
       | from your side to spend time on community, especially if you have
       | strong opinions on README look.
       | 
       | I wonder only, how to scale it (: Is there a way for anyone to
       | help with this effort, while not spending O(n) time. Automation?
        
         | zakki wrote:
         | A template of a README with an example of outstanding README
         | may help on wider scale.
        
       | nickjj wrote:
       | Beyond covering the "why" and the problem your tool solves it's
       | also IMO a really good idea to include a "why use this over XYZ"
       | section if your tool happens to have a few popular alternative
       | libraries or is similar to something that most folks in your
       | niche already knows.
       | 
       | Because if your tool is new, one of the first things folks are
       | going to think is "why wouldn't I continue using XYZ?". The goal
       | of this question isn't to put down the competition but it should
       | draw comparisons between the tools and include the reasons why
       | you created your tool. This could be adding certain features,
       | doing things faster or whatever makes sense.
       | 
       | Flask-Classful's docs https://flask-classful.teracy.org/ has an
       | excellent example of the above. The opening paragraphs cover it
       | so well. The rest of the docs are also a good baseline example
       | for creating useful documentation. Lots of practical code
       | examples with very clear explanations of how it works.
        
         | sundarurfriend wrote:
         | Even without detailed comparisons, a "Related projects" section
         | is very useful to the user. Sometimes I see such a section with
         | comments on the other projects like "ProjectA: in case you want
         | features X and Y", or "Project D: emphasises minimalism and
         | configurability", and that is both immensely useful and
         | increases my confidence in the current project whose README I'm
         | looking at. It makes it clear that the author has your best
         | interests in mind and understands their project's strengths and
         | weaknesses.
        
       | cdubzzz wrote:
       | I really appreciate folks who commit time to open source projects
       | for things other than code (e.g. things that may be otherwise
       | neglected).
       | 
       | There was a user on GitHub back in 2019[0] who went around and
       | created logos for a bunch of projects (including one I was
       | working on actively at the time). Out of curiosity I looked the
       | account up recently while working on a new project but it's not
       | longer active.
       | 
       | Translations are another great example of this. That same project
       | that got the logo has also been translated by various people in
       | to eight different languages!
       | 
       | Other ways I'd love to find people devoting time to smaller
       | projects -- accessibility and UX audits. It's hard to account for
       | all this stuff on smaller projects with only one or two primary
       | developers.
       | 
       | [0]
       | https://github.com/reallinfo?tab=overview&from=2019-12-01&to...
        
         | m463 wrote:
         | > accessibility and UX audits
         | 
         | I _so_ very much agree. I think user interface design and
         | inconsistency is really holding linux back. Accessibility is
         | intertwined with it.
         | 
         | I think if someone who did game ui design paired with a blind
         | person could critique linux distributions (that led to
         | changes), we would all benefit.
        
         | ChrisMarshallNY wrote:
         | This.
         | 
         | Especially the localization bit. I'm constantly surprised to
         | encounter folks that never even think about it, until version
         | 1.5, and then find out that localization is a _nightmare_ to
         | add, after the fact.
         | 
         | And getting folks to work with them, is just as nightmarish.
         | 
         | Good RoT for localization is native, _local_ speaker of the
         | language, and dialects need to be considered. It 's quite
         | possible to bust your ass, getting a Spanish translation, only
         | to have a lot of upset Latin-American users, because the
         | translation was done in Castilian Spanish, as the only person
         | who could handle the tech involved in localization was a CS
         | student in Madrid.
         | 
         | I've learned to factor localization in from the beginning; even
         | if I'm _sure_ that this will never be used outside of my
         | country (which isn 't actually fair. There's neighborhoods in
         | Brooklyn, where English is not the primary language; even
         | though everyone was born here).
         | 
         | You just need to get to the point where you have to add
         | localization after the fact -once, to get religion.
         | 
         | Localization is difficult and expensive. If we want people to
         | help us localize, it is incumbent upon us to make it easy and
         | relatively tech-free.
         | 
         | Or we can pay _beaucoup bucks_ to iBabble-On (who do a great
         | job, but not for free).
        
       | rwmj wrote:
       | Many READMEs would be greatly improved with a one paragraph
       | introduction to the topic, defining all the terms used and
       | outlining the problem that the project is trying to solve.
        
       | hobofan wrote:
       | I think that's a great service for projects that want more users
       | (whether that's a good idea/goal is another topic)!
       | 
       | On my own projects I've seem a pretty clear divide in adoption
       | between projects which have a good README (100+ stars) and
       | projects which have a similar level of utility/maturity but where
       | I didn't bother to write a proper README (0-5 stars). (Stars are
       | often a bad proxy for adoption, but here they are roughly
       | proportional to downloads, reported issues, etc.)
        
       | mxcrossb wrote:
       | > A README is meant for someone who is first encountering the
       | project to be able to quickly decide if they want to learn more
       | about it.
       | 
       | In the past, by time I got to the readme I had already downloaded
       | the project. It's kind of weird how places like GitHub rendering
       | the readme have changed the practice.
        
       | polote wrote:
       | > I'd like to help others make better free and open source
       | software so I'm making this standing offer: I'll review your
       | README for free.
       | 
       | On a more global discussion, I feel like a lot of experienced
       | people are willing to help, or teach for free on subjects such
       | as, startups, programming, product management, data science, tech
       | subjects ... (and I assume on other non-tech topics also) but it
       | is always hard to find people to help. I mean you could join a
       | charity, but it is not the same thing as being close to one
       | person and helping him in topics he is not good at.
       | 
       | Does anyone know a community where one can find people to help
       | individually ?
        
         | ChrisMarshallNY wrote:
         | As an older person that has done quite a bit of free teaching,
         | I'd gently suggest that a good start would be to have the
         | current generation be a little more generous towards us.
         | 
         | A lot of us are, indeed, tiresome old "OK boomers," but some of
         | us (I'd like to think I'm one) may actually have something to
         | contribute.
         | 
         | Here's an example of a simple course I gave on Core Bluetooth.
         | It was not free, but try! Swift World does their courses for
         | $50 a pop, which is pretty cheap (BTW: I donated the proceeds
         | for my class to sponsor scholarships to other classes):
         | https://www.linkedin.com/posts/chrismarshallny_try-swift-wor...
         | 
         | Take note of the course materials. They basically teach the
         | class on their own (also, they are entirely driven by some
         | _very_ intense READMEs).
         | 
         | In my experience, a couple of the better teachers on try! Swift
         | World are relatively older ones, like Erica Sadun and Daniel
         | Steinberg. Some of the younger ones are also excellent.
        
         | [deleted]
        
       | nandi95 wrote:
       | I wish some people did that but for documentation
        
       | sfvisser wrote:
       | Pet peeve of mine: READMEs starting to explain hoe efficient,
       | performant or minimal something is without explaining wat it is
       | and why it should exist in the first place.
       | 
       | Or using overly vague terms that only make sense in a very narrow
       | technical context. A 'minimal isomorphic asynchronous worker
       | framework'. Can mean a million things.
        
         | frou_dh wrote:
         | Here's my README pet peeve: When the examples for some tool
         | that operates on source code show it operating on its own code.
         | 
         | As a reader unfamiliar with a project, it's unpleasant to have
         | to contend with "meta" at a time when one doesn't even have a
         | solid first-order understanding of the project.
        
           | nooyurrsdey wrote:
           | prism.js the code syntax highlighter is notoriously bad at
           | this.
           | 
           | At first I felt bad for being confused by something so
           | simple. But all their code examples for highlighting refer to
           | their own code and you're right, at the exact moment you're
           | trying to absorb new information it is infuriating to deal
           | with the "meta" examples.
           | 
           | I don't use them out of that alone.
        
             | slhck wrote:
             | This is my main issue with Rspec documentation.
        
               | pizzapill wrote:
               | RSpec has none of that, a typical example from the first
               | page of their documentation:
               | RSpec.describe Widget do         example do
               | expect(described_class).to equal(Widget)         end
               | end
               | 
               | Pretty non-meta.
        
         | jka wrote:
         | In some cases it is valid for a project to write for a
         | particularly niche audience; it may be difficult to write for
         | everyone. But yep, sometimes they may simply need help
         | improving their messaging.
        
         | DandyDev wrote:
         | To be fair, I think we're talking about READMEs for technical
         | projects here, probably hosted on Github/Gitlab/... And in that
         | context your example is totally clear to me: it's a framework
         | for running (background) jobs asynchronously (i.e. code that
         | does not need to run on the main thread of your program and
         | block) and you can use it both on the server and the browser
         | (so probably JS/TS) and it's not intended to be feature rich.
        
           | daveFNbuck wrote:
           | A lot of asynchronous job frameworks run workers on many
           | machines across a cluster. That's a very different sort of
           | framework than one that runs things in the background on a
           | single machine, but the short description applies equally
           | well to it.
        
           | nooyurrsdey wrote:
           | Sure the individual words make sense but there's a cognitive
           | load of deciphering that when you're first trying to learn
           | something.
           | 
           | A "plain english" no nonsense definition goes a long way to
           | introduce your concept. Save the fancy technical jargon for
           | further down in the README if you must.
        
             | bloopernova wrote:
             | That's a really good point.
             | 
             | I need to either find or write a good readme template with
             | that in mind.
        
             | erikerikson wrote:
             | You have a point and I might reprioritize.
             | 
             | Specialized terminology allows the communication of complex
             | concepts compactly. For the specialists a brief description
             | like you mentioned is perfect. If you give it first, that
             | person can read it and decide.
             | 
             | It should certainly be followed by a tear down or other
             | plain English explanation of what the thing is.
             | 
             | Kind of like: ``` Brief
             | 
             | A little longer
             | 
             | Be descriptive about the thing
             | 
             | Go into every detail you want to discuss about the thing in
             | the repository... ```
             | 
             | The jargon fooled blurb makes a great "a little longer" and
             | gets out of the way to let the more readable description be
             | given. Burying that can be a pain.
        
           | Y-bar wrote:
           | I'm not the person you responded to, but I think their peeve
           | stands correct for technical README's as well. I've decided
           | more than once to not continue reading those when is is not
           | clear to me to move on to what might be a similar
           | implementation just because the README never really explained
           | if it was what I was looking for.
           | 
           | The times when I need to read the repo README is when I am
           | not familiar with what I am looking for. I say err on the
           | side on more documentation, err on the side of a better
           | explanation.
        
         | colour wrote:
         | Code for asynchronous work, but it's isomorphic whatever that
         | means.
        
           | syspec wrote:
           | Nodejs
        
         | tirrex wrote:
         | fast, simple, scalable, modern, high performance, easy to use,
         | enterprise-grade, secure, production-ready, new generation,
         | lightweight ...
         | 
         | These are common words I see in the first paragraph of readmes.
         | If people can avoid these, they'll write better introductions.
         | No marketing, no subjective words. Otherwise, I feel like
         | someone is trying to sell me that product.
        
           | astatine wrote:
           | This sounds right, though it doesn't have to be. These type
           | of words signal the author's intent and when 1 - justified by
           | the actual deliverable 2 - substantiated with concrete data
           | can be very useful. They can help create the right
           | expectation. Unfortunately, they are more often misused or
           | abused than applied correctly.
        
             | latexr wrote:
             | > These type of words signal the author's intent
             | 
             | How many people intend to make slow, outdated, insecure
             | software?
             | 
             | > when 1 (...) substantiated with concrete data
             | 
             | Then show me the data and let me reach my own conclusions.
             | As a bonus point, the unquantifiable adjectives will be
             | removed.
             | 
             | > Unfortunately, they are more often misused or abused than
             | applied correctly.
             | 
             | Which makes them useless all of the time, because by now
             | we're primed to ignore those claims.
        
               | astatine wrote:
               | > How many people intend to make slow, outdated, insecure
               | software? The point is that some authors may claim
               | simplicity, some may claim performance, others more
               | security and so on. It is rare to have all adjectives
               | thrown in - and easy to discard when you see them.
               | 
               | >because by now we're primed to ignore those claims.
               | Unfortunately, we don't always. If we were ignoring them
               | all, then we wouldn't care. It is that we can't help read
               | and interpret them and have our expectations set up;
               | hence the disappointment when it turned out to be just
               | words.
        
           | nickjj wrote:
           | I think production ready on its own has value because it sets
           | the stage of what to expect.
           | 
           | There's a very big difference between a project being
           | production ready or not. Production ready (to me at least)
           | means the project has been thoroughly tested on a live site
           | and is in a position where you can take it as is and run it
           | in production with confidence that it's going to work.
           | 
           | For example I have a Docker + Flask example starter kit
           | project at https://github.com/nickjj/docker-flask-example and
           | the GitHub description is "A production ready example Flask
           | app that's using Docker and Docker Compose.". In this context
           | to me that says it's using multi-stage builds, env variables,
           | deals with static files in a way that's cacheable (md5
           | hashes, etc.), has tests and overall you can expect to see
           | patterns that work well in both dev and prod. The README goes
           | over those details too in case you didn't infer that from
           | only "production ready" too.
           | 
           | Plot twist: It took me longer to write the README than create
           | the whole project.
        
           | rendaw wrote:
           | I'd expect a fast json parser to be harder to use than an
           | easy-to-use or simple one. But if I need to eke out maximum
           | performance on something I'm going to skip the ones that
           | don't have fast in the description - it means the project's
           | goals aren't aligned with my use case. If it's a web project
           | then I'm going to focus on parsers that have have actually
           | considered security over the ones that haven't.
           | 
           | These are all important words for describing projects.
        
             | johnchristopher wrote:
             | Fast is not a KPI though. It can and is often labeled on
             | anything, making the term useless even when fast is a
             | criteria over ease of us.
             | 
             | Maybe something at the top along the lines of : what it
             | does, how and then what are the implications.
        
               | mikepurvis wrote:
               | Claiming "fast" implies that performance is a project
               | goal, possibly even tracked over time as a metric, and
               | that there's probably a comparison deeper in the README
               | or elsewhere. It probably also means that when it comes
               | to tradeoffs (compile time, code size, binary size,
               | ergonomics, maybe even strictness/correctness), runtime
               | speed is the preferred option.
        
             | s3ker wrote:
             | You forgot to add military-grade encryption and cloud-
             | native tags
        
           | lgreiv wrote:
           | I agree in general, except for `production-ready` which I
           | deem useful information. Of course, it is only the
           | maintainers' assessment on the state of the project and thus
           | needs to be validated further by myself. But IMO that
           | adjective signals that I can expect the author to be happy
           | with the current API and behavior and can assume it will be
           | relatively stable; probably battle-tested.
        
             | iudqnolq wrote:
             | I think "production ready" is essentially impossible
             | without also being able to say "I/my employer/foocorp is
             | running this in production" unless you're not allowed to
             | say it for legal reasons. I think it would take a very
             | experienced developer to predict in advance every issue
             | they'd run into putting something into production.
        
               | lgreiv wrote:
               | The definition you gave is exactly how I would read
               | `production-ready`. I might be overly optimistic in
               | assuming that this is the case whenever someone uses the
               | term, though.
               | 
               | > I think it would take a very experienced developer to
               | predict in advance every issue they'd run into putting
               | something into production.
               | 
               | I am not sure whether that can be expected from any
               | project that exceeds a very narrow scope and/or if which
               | it's correctness can potentially be mathematically
               | proven.
        
         | globular-toast wrote:
         | I'm so lost when looking at READMEs or web pages like that. It
         | will tell me that it's going to solve my problem faster and
         | better than all other solutions out there. But I still don't
         | know what my problem is.
         | 
         | Always start with the problem. Tools don't exist just for fun,
         | they exist because we need them.
        
       | DandyDev wrote:
       | Great initiative and very generous!
       | 
       | My pet peeve with READMEs: usage of excessive adjectives to
       | oversell your project. Famous culprits: "blazingly fast" or
       | software that is "beautiful" or creates "beautiful" things.
        
         | nabla9 wrote:
         | People are starting to adapt corporate PR and marketing jargon
         | as sign of professionalism.
         | 
         | Another way to make yourself appear silly influencer is to use
         | words like "I" and "My" in headlines ("I made a thing", "My
         | thing hobby", "My thoughts on .."). Obviously it's you. But
         | people don't know who you are and generally they don't care.
         | Pushing persona makes everything look like social media
         | marketing.
        
           | hakre wrote:
           | And not only such. In the end this is how marketing works,
           | there is always the feeling to be left: the feeling to be
           | part of the in-group.
        
         | nickjj wrote:
         | > My pet peeve with README
         | 
         | DHH had a funny line around Dropbox's "mission" in his 2019
         | railsconf video (linked to the direct point in the video):
         | https://youtu.be/VBwWbFpkltg?t=2818
         | 
         | Dropbox's official mission as of 2019 was: "We're here to
         | unleash the world's creative energy by designing a more
         | enlightened way of working"
         | 
         | And DHH's remark was: "For fuck's sake Dropbox, you host files
         | and make them appear on all of my computers"
         | 
         | Funny enough since then they changed their mission to be "Our
         | mission is to design a more enlightened way of working" based
         | on https://www.dropbox.com/about but it still doesn't come
         | close to explaining what they do.
        
           | tmotwu wrote:
           | Customers don't infer the purpose of a product from it's
           | company mission. The audience of a company mission are
           | employees themselves. Dropbox has expanded to more than file
           | syncing over the past decade. It makes sense to have a broad
           | vision of their future, e.g purposeful mission.
           | 
           | Imagine Amazon telling employees to stick it to books because
           | thats the business they started off with. Like why should AWS
           | even exist, it's not what they do! That narrow mindedness
           | wouldn't have gotten them to where they are today.
        
             | sundarurfriend wrote:
             | Zero people have looked at a mission statement like that
             | and thought "Ah, now I understand the scope and limitations
             | of my company, and will use that to direct my ideas".
        
       | mellosouls wrote:
       | The generous author's gitlab page fwiw for examples of his own
       | (it wasn't clear from the article):
       | 
       | https://gitlab.com/larswirzenius
        
       | kstenerud wrote:
       | I'd be curious to know how many takers he gets in the first day
       | after being featured on HN!
        
         | purplecats wrote:
         | The population size of HN seems much smaller than I originally
         | had imagined.
        
       | ttty wrote:
       | A README is meant for someone who is first encountering the
       | project to be able to quickly decide if they want to learn more
       | about it. I'm willing to spend an hour per project, in total. I
       | choose which projects to work on and how many projects.
       | 
       | A README should have an example of how to typically use the
       | software. It should say how the copyright and other legal aspects
       | affect the project. A README can also contain instructions for
       | installing the software, or how to run its test suite.
        
       | tyingq wrote:
       | _" Queue status, in case you're waiting: 70 in queue, 6 reviewed,
       | oldest in queue: 2021-04-15 13:30 UTC"_
       | 
       | Guessing that queue is getting deeper now. Maybe he should add a
       | nominal fee to jump the queue ;)
        
       | yboris wrote:
       | If the repository is of an application, I strongly recommend
       | people include a screenshot of it.
       | 
       | It blows my mind when someone has spent hundreds of hours to make
       | something that they'd like others to use, and didn't spend the 5
       | minutes needed to increase its use by (my estimate) at least 5%.
        
         | ziml77 wrote:
         | At least one screenshot is nice. A demo video or GIF is
         | amazing.
        
         | daptaq wrote:
         | The issue here is that it is meaningless when viewed locally.
         | GitHub made the mistake of turning "README", a file you'd
         | usually read when you download some code into a website format.
         | A README is broken if lines aren't broken, it is full of badges
         | or nonsense like a table of contents (as OP says, a README is
         | not a manual).
        
           | asutekku wrote:
           | To be fair, i haven't read a local readme in years. Markdown
           | in github is hands down miles better and provides more value
           | than any local readme openable with any kind of computer
           | could provide.
        
             | daptaq wrote:
             | IMO a valid, human readable README file is will always also
             | generate readable rendered output.
        
           | atleta wrote:
           | It's not. You can include images in markdown and markdown
           | being markdown, the links are pretty easy to identify and
           | then open.
           | 
           | They don't have to, or better to say the shouldn't, be
           | absolute http links. They can be just relative ones, and
           | those will translate very nicely into file paths locally. If
           | you just use a plain text editor you'll have to open them
           | manually. A bit smarter one (e.g. most likely your IDE) will
           | turn them into clickable file links. You're not losing
           | anything but whoever looks at it on the web will have a lot
           | better idea. And most people will look at it on the web
           | first, before cloning the repo locally... Because it saves
           | time.
        
         | pcthrowaway wrote:
         | A good README is unlikely to be 5 minutes of time. I've spent
         | ~5 hours on what I consider "OK" READMEs for our internal
         | projects where I have a captive audience (so don't need to sell
         | them on it)
        
           | yboris wrote:
           | Adding a screenshot to a README would likely take about 5
           | minutes. Put your app over a white background, take a
           | screenshot, trim it, paste it in a commend under "Issues" and
           | copy the GitHub-generated shortcode/url for it.
        
             | k4rli wrote:
             | Pasting to an issue to get an easy image upload is a nice
             | trick, thanks!
        
         | MaxBarraclough wrote:
         | > I strongly recommend people include a screenshot of it
         | 
         | Related: if your project has a website, include a screenshot on
         | the front-page, not buried somewhere. A clickable thumbnail is
         | fine, just don't make the reader work for it.
         | 
         | Might also be worth having a video of the application in
         | action.
        
       | teddyh wrote:
       | The rules for traditional README files are documented here:
       | 
       | https://tldp.org/HOWTO/Software-Release-Practice-HOWTO/distp...
       | 
       | https://www.gnu.org/prep/standards/standards.html#index-READ...
        
       | cpursley wrote:
       | I won't even consider projects who's READMEs don't include enough
       | info on what it is and basic steps for bootstrapping it up.
        
       | ozzmotik wrote:
       | I think I need a README for writing a proper README.
        
       | jka wrote:
       | This is a great idea, and worth encouraging.
       | 
       | Some tips to be aware of in order to maintain a healthy
       | contributor/maintainer ecosystem:
       | 
       | Bear in mind the volume of requests that the project/maintainers
       | may have to deal with. This is usually fairly open and
       | transparent with most FLOSS projects.
       | 
       | It's always good to test and understand your changes before
       | submitting them - and if you can demonstrate that to the
       | maintainers (by way of test coverage, screenshots, console
       | output, etc), that'll increase the likelihood that your changes
       | can be accepted, and can increase your reputation for respecting
       | maintainer time.
       | 
       | If you feel like you _didn't_ fully test/understand your changes
       | and they _were_ accepted regardless, that could be a sign that
       | the project needs a bit more help with review and quality
       | control. That can be a challenge, and it can also be an
       | opportunity to provide other improvements (for example, by code
       | reviewing and/or increasing test and continuous integration
       | coverage).
       | 
       | PS: It might sound like a lot of this refers purely to code
       | changes - but READMEs and documentation can be equally important
       | to keep correct.
        
       | noxer wrote:
       | I wish people would find a way to include any code present in a
       | README in some kind of automated test.
       | 
       | Nothing more frustrating than if you copy something from there
       | but it turns out the README wasn't updated since the very first
       | day and all the "hello world" code or install instructions are
       | completely outdated
       | 
       | Maybe not include any code is the better solution, instead add an
       | example folder.
        
         | Gadiguibou wrote:
         | That's included in Rust![1]
         | 
         | Code examples from the documentation automatically become
         | "documentation tests" to make sure your examples are still up
         | to date when updating your code.
         | 
         | [1] https://doc.rust-lang.org/rustdoc/documentation-tests.html
        
           | Omin wrote:
           | The README.md isn't part of the rust code, so it's not
           | checked by this unless you use tools to generate your README
           | from doc comments like https://github.com/livioribeiro/cargo-
           | readme.
        
             | Rompect wrote:
             | Actually, it's possible and even frequently used, for
             | example in lazy-static, through the `doc_comment` crate.
             | #[cfg(doctest)]         #[macro_use]         extern crate
             | doc_comment;                  #[cfg(doctest)]
             | doctest!("../README.md");
             | 
             | Now, the readme examples are tested like everything else.
             | 
             | https://github.com/rust-lang-nursery/lazy-
             | static.rs/blob/mas...
        
         | an_ko wrote:
         | I've written this tool to test example code in markdown
         | documents using user-specified shell commands:
         | https://github.com/anko/txm I have had great success using it
         | in my own projects, so perhaps others might find it useful too.
        
         | boxed wrote:
         | You'll like this
         | https://kodare.net/2020/10/23/100_percent_coverage_docs.html
         | it's my journey to 100% coverage for all code samples in ALL
         | the documentation for iommi.
        
         | SuperCuber wrote:
         | I do something similar: my README contains the output of
         | --help, and I have a CI step that ensures that all the lines of
         | the _actual_ help output are present in the README. Caught me a
         | couple times forgetting to update new flags and version
         | changes.
        
           | M3t0r wrote:
           | I've spent hours putting that functionality into a unit test.
           | Worth every minute!
        
         | kstenerud wrote:
         | One thing golang did right is the go playground. When I put
         | code in my README, I also include a playground link.
         | 
         | Example: https://github.com/kstenerud/go-concise-
         | encoding#library-usa...
        
         | tele_ski wrote:
         | This is great advice and I wish it was the standard. I had this
         | problem on one of my projects so I used a githook to basically
         | paste in actual compiled example files from the test suite on
         | committing. It does mean the actual readme is more like a
         | template and you can't edit the README file directly anymore
         | but all the examples always work now!
         | 
         | I personally like at least one small example embedded in the
         | README since it's zero effort, an example folder is great for
         | _more_, but annoying to get started, what should I look at in
         | the example folder first?
        
         | ehershey wrote:
         | This is brilliant!
         | 
         | It's one of those things that's so easy to forget or not even
         | think about but once you see it or think about it, it's
         | essential.
        
         | kevin_thibedeau wrote:
         | Generate it with an m4 include.
        
         | franciscop wrote:
         | I did that! I hope you are not the person who suffered that
         | from me (did you use Picnic CSS a few years back?). So for a
         | newer project I put some setup code that will look for all code
         | snippets with a specific comment and run that with the code
         | after the comment. For generating the website documentation
         | that test bit can be stripped (though I kept it for now).
         | 
         | Example:
         | https://github.com/franciscop/server/blob/master/docs/docume...
        
         | thejosh wrote:
         | I like this about elixir, in the documentation you can use
         | exdoc to make sure that the code examples actually work, and
         | provide code samples that are tested. It makes reading
         | documentation for projects quite nice.
        
       | [deleted]
        
       | rmetzler wrote:
       | It's a really nice offer.
       | 
       | I found one small typo: "Part of the~~w~~ review process"
       | 
       | I'm sorry, it's kind of a trigger for me to read READMEs with
       | typos and I need to send a PR to fix it.
        
       | jjjjjjjj1 wrote:
       | Be careful: An Email Account linked to README and public
       | repository is considerable as privacy information.
        
         | jjjjjjjj2 wrote:
         | Yes. I agree.
        
       ___________________________________________________________________
       (page generated 2021-04-17 23:01 UTC)