Improve CDNJS documentation

[dakshshah96]

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.

cc @PeterDaveHello

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[PeterDaveHello]

@dakshshah96 thanks for your proposal, it looks cool, and we'll need some time to have a detail plan about how do we do that, give me more time to think about it, and feel free to have a talk on https://gitter.im/cdnjs/cdnjs, thank you again!

cc @cdnjs/dev @cdnjs/team-cdnjs

[dakshshah96]

For now, it feels like we should stick to a single CONTRIBUTING.md file for our contribution guidelines since that'd be a more straight forward approach. Here's a rough roadmap of the new contribution document I'm proposing. Please feel free to suggest any changes.

• Introduction: About this repository, welcoming contributors to CDNJS and basic introductory help for new contributors.
• Table of Contents: List out all the important sections of the contribution document to make navigation easy.
• Ways to Contribute: An outline of what type of contributions someone can make to the CDNJS repository.
• Forking the Project
  • Setting up your system
  • Forking cdnjs
  • Cloning your fork: Include important details about sparse-checkout, setting up remote repositories, shallow pull, etc.
  • Maintaining your fork: How-to guide on keeping the CDNJS fork up-to-date.
• Start Contributing: This section is all about showing contributors how to actually make changes
  • Find issues to work on: If contributor wants to work on an already existing issue
  • General Conventions: reminder to update fork before creating branch, info on good commit messages, and link to guidelines on addition of new library.
  • Creating and adding your branch: importance of branch naming, how to create and push a branch.
  • Making commits: commands for making commits, guidelines for making good commits such as naming and other conventions.
    • Squashing commits: how to squash multiple commits
• Creating a Pull Request
  • Introduction and important basic guidelines: for example, always editing on a branch and not master
  • Methods: Local and GitHub interface
    • Editing via your local fork: Detailed instructions on branching, adding, committing, squashing and pushing.
    • Editing via the GitHub interface
      • Include not recommended warning: since updating fork is not possible
      • Steps on how to commit on the interface
    • Common Steps: instructions on the common steps both local and GitHub interface contributors have to follow to make a pull request.
• How we review and merge pull requests: description of the review process by moderators
• Guidelines for adding a new library: This section outlines the specific guidelines for adding a new library to CDNJS
  • The package.json file: talks about the most important file for any library on CDNJS
    • Auto updating libraries: instructions on using auto update
      • npm auto-update
      • git auto-update
  • Adding a new library via the GitHub interface using single package.json file
  • Adding a new library with assets from your local fork
    • Location and naming of library directories
    • Creation of package.json file
    • Fetching the files for the latest version of the library being added
    • Using tools to test and auto correct your changes: This will link to the main section below on tools
• Tools for your convenience
  • fixFormat.js: instructions on how to fix the format of package.json using the fix format tool
  • web-minify-helper: instructions on using the auto-minifier to minify files and generate .map files for debug

cc: @PeterDaveHello Please let me know if anything is missing in the roadmap. Once we have this finalized, I can start working on this. I already have a lot of content from this ready with me. 😄

[drewfreyling]

@dakshshah96 looks thorough. Couple of questions though:

• Why do we care how they name their branches on their fork?
• Information on setting up remote repos - why should we include this? Shouldn't we assume people have a basic understanding of git?
• "how to create and push a branch", "commands for making commits" - as above

[dakshshah96]

@drewfreyling Thanks for the feedback.

• Just replicated what's mentioned in the pull request template — "Pull request is sending from a non-master branch with meaningful name".

• Regarding the basics — This is a huge step towards making the project more beginner-friendly. Since my time here on cdnjs, I've noticed a large number of pull requests coming from first-time contributors. Many of them are confused about the basics and we, the maintainers have to spend time in explaining them individually in the PRs. Including this information in the document would make maintenance easier. This will also encourage many people who wouldn't have contributed because they had no idea on how to get started in the first place. That's the spirit of open source after all 😄

[PeterDaveHello]

LGTM 👍 , I believe those whom have enough git skills would bypass some of the doc sections by themselves.

@dakshshah96 would you like to help correct all the English issues in current doc, so that we can have a better doc before the whole new doc written?

[dakshshah96]

@PeterDaveHello Yes. Definitely! I'll make a PR soon.

[PeterDaveHello]

@dakshshah96 Great, thanks

[LeaSak]

Hi @dakshshah96 and @PeterDaveHello. I was wondering if you still need some help in copy editing the documentation? I'd be glad to contribute to the project. I'm completely new to the open source community but I have some editing experience. I noticed a few minor things with the README.md for example.

[PeterDaveHello]

@LeaSak sure thing and thank you! You're very welcome to join! I think @dakshshah96 is in busy right now, if you don't mind, I'd hope if we can have some minor fix of current document, just about the grammar or spelling issues, the not so big changes. What do you think?

[LeaSak]

@PeterDaveHello, Great! I'm excited to help. Yes, I mean what @dakshshah96 described as minor above, just spelling, grammar, punctuation. I'll start with the README.md and send my suggestions as a PR if that's okay?

[PeterDaveHello]

@LeaSak Sure thing!

[MattIPv4]

cc @AmNotADev

[AmNotADev]

Before in the next few days, I will be handling the initial commit to the new-docs repository with drafted documentation clearing all of the docs issues here on this repository.

I will be moving all issue responses over there until we can get all of the documentation finalized. Please follow up with me in this thread if you have questions or concerns you want me to take into account before I finish my drafts.

[AmNotADev]

To give an overview of tasks, the new docs will include (with some extras thrown in as needed):

General

• Readme
• Submitting
• Contributing
• Code of Conduct
• Resources
• Branding Guidelines
• PR Template

Issue Templates

• Problem
• Suggestion
• Discussion
• Add Library

Wiki

• Introduction
• Getting Started
• Contributing
• Submitting & Updating
• Code of Conduct
• Resources
• About cdnjs

Legal Docs

• User Agreement
• Privacy Policy

[ericm]

Looks good! It'd be nice if you set up the new-docs repo with GitHub pages as well using jekyll or something for now to make the docs easy to read.

[MattIPv4]

cdnjs has changed quite significantly since this issue was created and even since the last update was posted here -- package configurations are now based out of cdnjs/packages with a completey new auto-update system. We've also got the start of new docs being written there.

As such, I think it best this is closed for now and we can look at creating new issues where relevant for new docs as needed (eg. the WIP new website may need User agreement/Privacy policy docs).