Principles for creating consistent, idiomatic GitHub projects.
Please help improve this document! Contributions are welcome.
Everyone has preferences, and everyone has their own view of what makes a project "idiomatic". My own preferences are no exception. I created this project for a few reasons:
-
As a guide and reminder to my future self, about what has worked and what hasn't in projects past. From this standpoint, this guide represents ideas that have been battle-tested on more than 500 projects, a great number of which have been the product of some kind of boilerplate that I created or maintained.
-
As a living document that, with the help of the community, will improve over time, so that I can improve my own organization habits over time.
-
Last, because everyone has preferences and their own view of what makes a project "idiomatic". While creativity and differences are what makes the world an interesting place, when applied to the organization structure of similar projects - those things also make it difficult for communities to grow, teams to collaborate, and standards to be adopted.
As a general rule, do not publish a project until most of it has been documented. I didn't always follow this rule, and their are a few exceptions, but here is what I've learned:
-
A project that isn't documented might as well not exist. No one besides the author gets value from a project that isn't documented, which means no one besides the author uses it, and no one besides the author contributes.
-
When documentation is poor or misleading, much more time will be spent addressing bug reports or issues resulting from misunderstandings than would have been spent had you properly documented the code, API, usage, or whatever your yet-to-be-realized community will need to know about your project.
-
Documentation isn't just nice-to-have, it can mean the diffence between having an "interesting" project, a project that no one notices, and a hugely popular project. I believe that awesome documentation has played a huge role in the success of some of GitHub's most popular projects.
-
Oftentimes users of large projects will become so familiar with the code, or get to a point where they have "outgrown" what's currently written in the documentation, that I usually see these users divide into roughly the following categories: 1) some will create issues about it, or complain, 2) others will offer to help improve the documentation or contribute in some other way. Remember that most open source projects on GitHub are maintained by someone like you. Try to be in the second category and offer to help whenever possible. It's also helpful to create issues to improve the documentation, but only when you properly describe the problem, link to any erroneous information or typos, or offer a better solution. But it's even better if you do a pull request to fix it.
TODO:
Sections I plan to implement:
- idiomatic contributing
- proper documentation: API, usage, features
- proper attribution, giving credit to others
- project metadata: make it easier for others to find your project
Jon Schlinkert
Copyright (c) 2014 Jon Schlinkert, contributors. All documents in this repository are released under the Creative Commons Attribution 3.0 Unported License.
This file was generated by verb-cli on August 15, 2014.