Description
The importance of documentation
I've been actively contributing to CDNJS for the past couple of weeks and it has been a truly delightful experience working with CDNJS maintainers and fellow contributors. They've been highly supportive.
In the process of contributing, I've come to realize how important CDNJSs mission is for developers. However, with great power comes great responsibility.
Open source projects are usually self-promoted by their easy to read, organized, and exhaustive documentation. Great examples include Backbone.js, Can.js, jQuery++, Underscore.js, jQuery, HTML5 Boilerplate, Require.js, Twitter Bootstrap, and many more. Just as writing good code and great tests are important, excellent documentation helps others use and extend a project.
The current state of CDNJS documentation
The current CDNJS documentation is good. It's pretty good when compared to majority of the open source projects hosted on GitHub. However, it can be better.
Currently, the following places loosely host the documentation for CDNJS:
- README.md: This is the landing page for anyone visiting the CDNJS repository on GitHub.
- documents directory: This directory contains a few readme files for the API, the auto update functionality and sparse checkout feature for those working on the project locally.
- CONTRIBUTING.md: This is the main guide for people looking to contribute to the CDNJS project.
- CDNJS wiki: The wiki currently consists of only one page titled Extensions, Plugins, Resources.
In my opinion, these are few of the problems with the current documentation:
- MAJOR: The documentation is scattered across several places making it difficult for new contributors and even seasoned ones to look something up.
- MAJOR: Several important guidelines are missing from the documentation. Few which are at the top of my mind include commit message styles, instructions for debugging problems with pull requests with CDNJS tools and more.
- MINOR: Most of the documentation is laced with grammatical errors. I understand that English is not the first language of maintainers and I'd be more than happy to help.
Why GitHub wiki pages?
GitHub Wikis are a place in your repository where you can share long-form content about your project, such as how to use it, how it's been designed, manifestos on its core principles, and so on. Whereas a README is intended to quickly orient readers as to what your project can do, wikis can be used to provide additional documentation.
Wikis can be edited directly on GitHub, or you can work with a text editor offline and simply push your changes. Wikis are also collaborative by design.
What next?
If the maintainers of CDNJS are comfortable with it, I'd like to work on revamping the documentation using wiki pages. Right now, we can start with a roadmap of issues that need to be solved and work on them one-by-one.
Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.