Added guide for potential contributors

[jungshadow]

This should close #93 when merged.

[cjerdonek]

One thought: I was thinking this could go in the docs directory alongside the style guide. (The "best practices" guide for feeds could also go in the docs directory.) For more visibility, you could link to how to contribute in the README (GitHub supports internal relative links, e.g. docs/contributing.md). By the way, I put "history" at the top level because I view it as project metadata at the same level as a readme or license file.

[cjerdonek]

One more thought: you might want to link to the style guide in the contributing doc (e.g. in the bullets for creating a pull request).

[jungshadow]

@cjerdonek Personally, I like the idea of CONTRIBUTING.md and STYLEGUIDE.md (not capitalized as of yet) being at the top-level of the repository as it details how to contribute and isn't documentation related to the specification (i.e. to me it falls into the project metadata category you mention).

[cjerdonek]

@jungshadow I see your point about maintaining a distinction between external-facing docs and internal project docs, something I agree with. I guess my point was more that when you start having more than one of something (e.g. "contributing" and "style guide"), I usually create a folder for it so as not to clutter the top level. I was making a distinction between the history file and other internal project docs.

[jungshadow]

I talked bit with @demcg about this on Friday and I believe we're of the same mind on this. On a related note, I'd like to create a separate repository to house the documentation, which will help with hosting/building this on Read the Docs. Any other thoughts on this? /cc @pstenbjorn @jdmgoogle @pkoms @nomadaisy

[pstenbjorn]

@jungshadow I agree with using Read the Docs and having a separate Doc repo.

[cjerdonek]

I'd strongly recommend keeping the docs in the same repo as the spec. (This is also how most projects that I'm familiar with do it, as well as what Read The Docs says to do in their documentation.)

A couple advantages of doing it this way are that 1) the docs stay in synch with the version of the spec they are documenting (even when creating feature branches, etc), and 2) doc changes can be committed simultaneously with spec changes (which means you don't need to cross repos when adding to or viewing changes to the docs).

[jungshadow]

@cjerdonek I didn't see a hard-and-fast recommendation in the Read the Docs documentation, but that sounds reasonable. Additionally, we can add to CONTRIBUTING.md that, with a spec change, the documentation must be kept up-to-date (once we have the documentation, that is).

So here's the plan:

1. Leave the docs folder for use for specification-related docs when we have them. I'm leaning toward the Markdown option.
2. Move STYLEGUIDE.md to the root (NB: All of the "metadocs" in the root are docs that I'd like any potential developer to read/access first. Additionally, if folks don't want to read through the README, they can have quick access to the metadocs of their particular focus/choice, using the directory listing as a makeshift menu of sorts).

Assuming that all makes sense, I'll merge today.

[cjerdonek]

@jungshadow okay, thanks.

By the way, if you find that Markdown isn't flexible enough in terms of layout and styling options (e.g. in the way of providing what you already have here), another possibility to look at for the longer term would be auto-generating the bulk of the HTML using templates. For example, you could have an HTML template snippet for a single object type. This would let you change the global structure and look-and-feel more easily by modifying things in one place. This would take a bit more work to set up though, so would be a longer term project.

[jungshadow]

I only merged CONTRIBUTING.md. To be radically clear, the other structural changes I talked about will be in another issue and PR.

[jungshadow]

Interesting side note to this, after merging the CONTRIBUTING.md file, this alert now shows up on the issues/PR page. 👍