Adding instructions

content/en/docs/Concepts/_index.md

@@ -3,11 +3,10 @@ title: "Concepts"
 linkTitle: "Concepts"
 weight: 4
 description: >
-  A short lead descripton about this section page. Text here can also be **bold** or _italic_ and can even be split over multiple paragraphs.
+  What does your user need to understand about your project in order to use it - or potentially contribute to it? 
 ---
+For many projects, users may not need much information beyond the information in the [Overview](/docs/overview/), so this section is optional. However if there are areas where your users will need a more detailed understanding of a given term or feature in order to do anything useful with your project - for example if you have a large project with many components and a complex architecture - put that information in this section.
+
+Remember to focus on what the user needs to know, not just what you think is interesting about your project! If they don’t need to understand your original design decisions to use or contribute to the project, don’t put them in, or include your design docs in your repo and link to them. Similarly, most users will probably need to know more about how features work when in use rather than how they are implemented. Consider a separate architecture page for more detailed implementation and system design information that potential project contributors can consult.
 
-This is the section landing page.
 
-* Summarize
-* Your section
-* Here

content/en/docs/Contribution guidelines/_index.md

@@ -6,8 +6,4 @@ description: >
   How to contribute to the docs
 ---
 
-This is the section landing page.
-
-* Summarize
-* Your section
-* Here
+TODO: Add some boilerplate doc contribution guidelines

content/en/docs/Examples/_index.md

@@ -0,0 +1,13 @@
+
+---
+title: "Examples"
+linkTitle: "Examples"
+weight: 7
+date: 2017-01-05
+description: >
+  See your project in action!
+---
+
+Do you have any example applications or code for your users in your repo or elsewhere? Link to your examples here.
+
+

content/en/docs/Overview/_index.md

@@ -3,11 +3,29 @@ title: "Overview"
 linkTitle: "Overview"
 weight: 1
 description: >
-  A short lead descripton about this section page. Text here can also be **bold** or _italic_ and can even be split over multiple paragraphs.
+  Here's where your user finds out if your project is for them.
 ---
 
-This is the section landing page.
+The Overview is where your users find out about your project.  Try answering these questions for your user in this page:
+
+## What is it?
+
+Introduce your project, including what it does or lets you do, why you would use it, and its primary goal (and how it achieves it). This should be similar to your README description, though you can go into a little more detail here if you want.
+
+## Why do I want it?
+
+Help your user know if your project will help them. Useful information can include: 
+
+* **What is it good for?**: What types of problems does your project solve? What are the benefits of using it?
+
+* **What is it not good for?**: For example, point out situations that might intuitively seem suited for your project, but aren't for some reason. Also mention known limitations, scaling issues, or anything else that might let your users know if the project is not for them.
+
+* **What is it *not yet* good for?**: Highlight any useful features that are coming soon.
+
+## Where should I go next?
+
+Give your users next steps from the Overview. For example:
+
+* [Getting Started](/getting-started/): Get started with $project
+* [Examples](/examples/): Check out some example code!
 
-* Summarize
-* Your section
-* Here

content/en/docs/Reference/_index.md

@@ -1,13 +1,9 @@
 ---
 title: "Reference"
 linkTitle: "Reference"
-weight: 8
+weight: 9
 description: >
-  A short lead descripton about this section page. Text here can also be **bold** or _italic_ and can even be split over multiple paragraphs.
+  Low level reference docs for your project.
 ---
 
-This is the section landing page.
-
-* Summarize
-* Your section
-* Here
+If your project has an API, configuration, or other reference - anything that users need to look up that’s at an even lower level than a single task - put (or link to it) here.

content/en/docs/Tasks/_index.md

@@ -5,12 +5,17 @@ linkTitle: "Tasks"
 weight: 6
 date: 2017-01-05
 description: >
-  A short lead descripton about this section page. Text here can also be **bold** or _italic_ and can even be split over multiple paragraphs.
+  What can your user do with your project?
 ---
 
-This is the section landing page.
+Think about your project’s features and use cases. Use these to choose your tasks. Each granular use case (enable x, configure y) should have a corresponding tasks page or tasks page section. You can give each task a page, or you can group related tasks together in a page, such as tasks related to a particular feature. Users should be able to quickly refer to the Tasks section when they need to find out how to do one specific thing, rather than having to look for the instructions in a bigger tutorial or example.
 
-* Summarize
-* Your section
-* Here
+As well as grouping related tasks in single pages, you can also group task pages in nested folders with an index page as an overview, as seen in our example site.
+
+Each task should give the user
+
+* The prerequisites for this task (this can be specified at the top of a multi-task page if they're the same for all the page's tasks. "All these tasks assume that you understand....and that you have already....")
+* What this task accomplishes
+* Step by step instructions for the task as a numbered list.
+* If appropriate, links to related concept, tutorial, or example pages.
 

content/en/docs/Tutorials/_index.md

@@ -2,15 +2,11 @@
 ---
 title: "Tutorials"
 linkTitle: "Tutorials"
-weight: 7
+weight: 8
 date: 2017-01-04
 description: >
-  A short lead descripton about this section page. Text here can also be **bold** or _italic_ and can even be split over multiple paragraphs.
+  Show your user how to work through some end to end examples.
 ---
 
-This is the section landing page.
-
-* Summarize
-* Your section
-* Here
+Tutorials are complete worked examples made up of multiple tasks that guide the user through a relatively simple but realistic scenario: building an application that uses some of your project’s features, for example. If you have already created some Examples for your project you can base Tutorials on them. You may not need this section at first, but having tutorials can be useful to help your users engage with your example code, especially if there are aspects that need more explanation than you can easily provide in code comments.
 

content/en/docs/_index.md

@@ -1,14 +1,14 @@
 
 ---
-title: "Docsy Documentation"
+title: "Documentation"
 linkTitle: "Documentation"
 weight: 20
 menu:
   main:
     weight: 20
 ---
 
-This is a landing page for a top level section.
+This section is where the user documentation for your project lives - all the information your users need to understand and successfully use your project. We recommend adding content under the headings in this section, though if some or all of them don’t apply to your project feel free to remove them or add your own. Other content such as marketing material, case studies, and community updates should live in the [About](/about/) and [Community](/community/) pages.
 
 * Summarize
 * Your section