Initial samples and README

CONTENT.md

@@ -0,0 +1,30 @@
+----
+title: Content Sample
+author: John Doe <johndoe@example.com>
+description: This is a short, plain-text description of the content. It's optional, but may prove useful to others.
+first-written: 2015-02-24
+last-updated: 2015-02-24
+last-reviewed: 2015-02-24
+----
+This is my tutorial on how to write content! Welcome! Having some text before the first header can be useful.
+
+## First Heading
+
+Start at heading level 2. You're free to use any heading style you want, such as:
+
+Second Heading
+--------------
+
+Of course, subheadings are allowed also, and are in fact encouraged!
+
+### Third Heading
+
+If you want to write some Haskell code, you should mark it up like:
+
+```haskell
+main :: IO ()
+main = putStrLn "Hello World!"
+```
+
+And don't forget that linking to content ([](somecontent.md)) and to
+outlines ([](../outline/someoutline.md)) is a good idea.

OUTLINE.md

@@ -0,0 +1,29 @@
+----
+title: Outline Sample
+author: John Doe <johndoe@example.com>
+description: This is a short, plain-text description of the outline. It's optional, but may prove useful to others.
+first-written: 2015-02-24
+last-updated: 2015-02-24
+last-reviewed: 2015-02-24
+----
+
+You can use any kind of Markdown in an outline. But the recommendation is: give a short explanation in the intro of:
+
+* What this contains
+* Prior knowledge assumed
+* Recommended tooling to have installed to follow along
+* Possibly: how long it will take to complete
+
+Then set up your outline as flat lists in individual sections
+
+## Section 1
+
+* [](../content/subject1.md)
+* [](../content/subject2.md)
+* [](../content/subject3.md)
+
+## Section 2
+
+* [](../content/subject4.md)
+* [](../content/subject5.md)
+* [](../content/subject6.md)

README.md

@@ -1,2 +1,75 @@
-# haskelldocumentation
-Repository for collaborative Haskell documentation
+This repository is an implementation of the [intermediate Haskell documentation
+proposal](https://github.com/commercialhaskell/commercialhaskell/blob/master/proposal/intermediate-haskell-documentation.md).
+The goal is to have a repository where any documentation can be added,
+collaboratively maintained, and linked together in various outlines to provide
+a structured learning experience. Concretely: while the original proposal was
+specifically to enable "intermediate Haskell documentation," this repository is
+intended to support any kind of documentation.
+
+## Licensing
+
+All content in this repository is licensed [Attribution 4.0
+International (CC BY 4.0)](http://creativecommons.org/licenses/by/4.0/). By
+pushing content into this repository or sending a pull request, you are
+implicitly assigning that license to the content.
+
+## Commit access
+
+The goal of this repository is to be incredibly open about allowing
+contributors. If you would like to participate, open an issue asking for commit
+access, and odds are it will be granted. Similarly, odds are pretty high that
+just by sending a pull request you will be granted commit access.
+
+The general guidelines for how to treat your access is:
+
+* Any content for which you are the primary author, you should feel free to
+  make any changes to. If the changes are significant, feel free to reach out
+  to others for feedback.
+
+* You are free to make minor modifications and corrections to *any* content in
+  this repository, without consulting the original author. For more significant
+  changes, it is an expected courtesy to touch base with the author. If the
+  author appears to be non-responsive, check with others and, if there's general
+  consensus, move ahead with the changes.
+
+* Merging pull requests applies the same logic as above. If the changes are
+  minor or on your content, you may always do it. If they're significant, check
+  with the author.
+
+## Structure
+
+There are three main directories in this repository:
+
+* `content` contains all of the raw content. See the `CONTENT.md` file for an
+  example of what the content should look like.
+* `outline` contains various outlines of the content. See the `OUTLINE.md` file
+  for an example of what outlines should look like.
+* `src` contains various tooling to go along with this repository.
+
+The files in `content` and `outline` should be kept in a flat structure, i.e.
+no suubdirectories. Every file must end with a `.md` file extension. The result
+of this is that each content and outline file will have a unique identifier in
+the form of the filename, which can be used for linking.
+
+## Linking
+
+We should use standard Markdown linking conventions as relative paths. For example:
+
+* To link to a content file from another content file, the link would be `[link text](destination.md)`.
+* To link to a content file from an outline file, the link would be `[link text](../outline/destination.md)`.
+
+As a special feature, we *should* provide tooling that automatically fills in
+link text when not provided by grabbing the title from the destination. This
+would be triggered by having a link such as: `[](destination.md)`.
+
+## Embedding?
+
+This is *not* currently supporting. We may consider allowing importing of
+content from another file at some point in the future.
+
+## Authoring guidelines
+
+For now, please see [the original
+proposal](https://github.com/commercialhaskell/commercialhaskell/blob/master/proposal/intermediate-haskell-documentation.md#quality)
+for some recommendations on quality. Eventually, those guidelines should be
+moved into this document.