Why is it that most open source project pages are so terrible at documenting their own project?
I'm not talking about API or technical documentation - I'm talking about telling new visitors to your site what the hell your code is about.
Project authors, here are some handy tips:
- On your project front page, right at the top, put a simple explanation of what your code does (or what you hope it will do someday). Remember that your audience may not have the same level of technical experience as you do. Examples (screenshots, code snippets) are a MUST. A picture speaks a thousand words and all that...
- Make sure you include the development status of your project. I can't count the number of times I've spent 30 minutes looking at a project only to realize that it's not nearly complete enough to be usable to me. There's no shame in saying "this library is working, but not production ready. It is missing features X, Y, Z"
- Inject some enthusiasm! How many boring, dull, dry project descriptions do I have to read through? Most sound like the authors aren't passionate about their product. Sell your project; inject some enthusiasm, and maybe your viewers will become more enthusiastic in the process!
Well, that's my rant for the day. Now I must go update my project documentation...
Posts
View Thomi Richards's profile