I was watching Max Howell talk about creating brew yesterday at FrenchKit. As part of his presentation, he made a great point about how important it was for open source projects to have great readme files and I couldn't agree with him more.

As part of putting this newsletter together each week, I read a lot of readme files. As you might imagine, I have opinions on the subject. πŸ˜‚ Creating a really great readme is hard and it takes more time and care than you might imagine.

Does it start out by saying what the project actually does? You'd be surprised how many don't! Does it say how it will benefit the potential user? Does it spend more time talking about how to install it than it does saying how it will help you? If the library contains something visible, does it include a screenshot or two? If animation is important, are those screenshots presented as animated gifs? All of these things, and more are important.

As part of the discussion that happened on Twitter, Tim Searle bravely volunteered the readme from his Euclid library for a public critique. Hopefully it was an interesting thread if you want to give it a read.

If you maintain, or help to maintain an open source project, when was the last time you took a look at the readme file from the position of someone completely new to it? Could it be improved? Marketing isn't just for apps and services, it applies to open source libraries too! πŸ‘Œ

Dave Verwer  




macOS Development


And finally...