Define documentation contribution guidelines #1

Closed
jonah-williams opened this Issue Jan 16, 2013 · 4 comments

Projects

None yet

3 participants

@jonah-williams

Let's make it easy to contribute to this repository.

  • Discuss how to contribute to docs in the readme (current instructions only refer to CocoaPods proper).
  • Suggested style and content for Docs.
  • Suggested style and content for Guides.
@fabiopelosin
CocoaPods member

Discuss how to contribute to docs in the readme

What do you mean exactly?

Setting up this repo locally is a bit complex atm, I think that we should improve on it. Did you manage to get it running with the middleman locally?

Style

I think that the style should be:

  • Clear and concise: simple but accurate english, small sentences.
  • Accessible: leave out details that won't concern the 99% of the users if they would make things less confusing for the beginners.
  • Have and edge: ideally the language of the docs could have humorous hints, however this is not easy to get it right.
@jonah-williams

For "how to contribute" I think it's worthwhile to describe how we would like to see contributions to this repository. It can be as simple as suggestions to open issues or offer pull requests. Something to show that the repo is open to public contributions, that is it maintained, and that this is a good place to discuss changes (as opposed to CocoaPods/CocoaPods, mailing lists, or some other venue).
Just having a couple of issues in place will probably also help. My goal is to try to make it easy for users, especially new users who have found a problem trying to use the docs, to report (or fix) the issue. Let's make sure they don't have to guess what to do.
I'll write up an example in a pull request when I have a chance.

Middleman setup is fine I think. If that does prove to be a barrier we could setup a CI build to maintain an "edge" version of the guides for live previews of pull requests but I would want to make sure that's worth the effort before getting carried away.

I agree with all of the above points on style. Hopefully we can show style by example in existing docs but I find it useful to have some basic guidelines to remind me of the context I'm writing in. Again I'll try to offer a pull request.

@fabiopelosin
CocoaPods member

Good points.

@orta
CocoaPods member

Closing as this has been superseded by the guides.

@orta orta closed this Nov 27, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment