At the top of the file there should be a short introduction and/ or overview that explains what the project is. This description should match descriptions added for package managers (Gemspec, package.json, etc.)
Show what the library does as concisely as possible, developers should be able to figure out how your project solves their problem by looking at the code example. Make sure the API you are showing off is obvious, and that your code is short and concise.
| // Node.js CheatSheet. | |
| // Download the Node.js source code or a pre-built installer for your platform, and start developing today. | |
| // Download: http://nodejs.org/download/ | |
| // More: http://nodejs.org/api/all.html | |
| // 0. Synopsis. | |
| // http://nodejs.org/api/synopsis.html |
GitHub supports several lightweight markup languages for documentation; the most popular ones (generally, not just at GitHub) are Markdown and reStructuredText. Markdown is sometimes considered easier to use, and is often preferred when the purpose is simply to generate HTML. On the other hand, reStructuredText is more extensible and powerful, with native support (not just embedded HTML) for tables, as well as things like automatic generation of tables of contents.
