From 86729785d81d2807adf4bae194b9f391c4975777 Mon Sep 17 00:00:00 2001 From: Michael Snoyman Date: Tue, 24 Feb 2015 11:18:51 +0200 Subject: [PATCH] Initial samples and README --- CONTENT.md | 30 ++++++++++++++++++++ OUTLINE.md | 29 +++++++++++++++++++ README.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++-- content/.keep | 0 outline/.keep | 0 src/.keep | 0 6 files changed, 134 insertions(+), 2 deletions(-) create mode 100644 CONTENT.md create mode 100644 OUTLINE.md create mode 100644 content/.keep create mode 100644 outline/.keep create mode 100644 src/.keep diff --git a/CONTENT.md b/CONTENT.md new file mode 100644 index 0000000..5d2296c --- /dev/null +++ b/CONTENT.md @@ -0,0 +1,30 @@ +---- +title: Content Sample +author: John Doe +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. diff --git a/OUTLINE.md b/OUTLINE.md new file mode 100644 index 0000000..5a6e79f --- /dev/null +++ b/OUTLINE.md @@ -0,0 +1,29 @@ +---- +title: Outline Sample +author: John Doe +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) diff --git a/README.md b/README.md index e1b5b66..de6c244 100644 --- a/README.md +++ b/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. diff --git a/content/.keep b/content/.keep new file mode 100644 index 0000000..e69de29 diff --git a/outline/.keep b/outline/.keep new file mode 100644 index 0000000..e69de29 diff --git a/src/.keep b/src/.keep new file mode 100644 index 0000000..e69de29