silverstripe-framework/docs/en
Will Rossiter c477aade98 Add readme to include status of docs rewrite and high level todos
Conflicts:
	docs/en/03_Upgrading.md
	docs/en/03_Upgrading/00_Upgrading.md
	docs/en/03_Upgrading/index.md
2014-12-16 11:01:13 +13:00
..
_images Restructure of the docs markdown source files into more logical taxonomy 2014-12-16 11:01:12 +13:00
00_Getting_Started Restructure of the docs markdown source files into more logical taxonomy 2014-12-16 11:01:12 +13:00
01_Tutorials Restructure of the docs markdown source files into more logical taxonomy 2014-12-16 11:01:12 +13:00
02_Developer_Guides Restructure of the docs markdown source files into more logical taxonomy 2014-12-16 11:01:12 +13:00
03_Upgrading Add readme to include status of docs rewrite and high level todos 2014-12-16 11:01:13 +13:00
04_Changelogs Restructure of the docs markdown source files into more logical taxonomy 2014-12-16 11:01:12 +13:00
05_Contributing Restructure of the docs markdown source files into more logical taxonomy 2014-12-16 11:01:12 +13:00
changelogs Restructure of the docs markdown source files into more logical taxonomy 2014-12-16 11:01:12 +13:00
howto Restructure of the docs markdown source files into more logical taxonomy 2014-12-16 11:01:12 +13:00
installation Restructure of the docs markdown source files into more logical taxonomy 2014-12-16 11:01:12 +13:00
reference Restructure of the docs markdown source files into more logical taxonomy 2014-12-16 11:01:12 +13:00
topics Restructure of the docs markdown source files into more logical taxonomy 2014-12-16 11:01:12 +13:00
index.md Merge remote-tracking branch 'origin/3.0' into 3.1 2013-10-07 16:18:20 +02:00
README.md Add readme to include status of docs rewrite and high level todos 2014-12-16 11:01:13 +13:00

Todo

This folder is a work in progress for the new SilverStripe.org documentation project run by Cameron Findlay and Will Rossiter. If you want to contribute we'd love you too so flick us a message via email or twitter.

The docsviewer module issue tracker has a set of functional requirements that we need to make as part of this work.

At the current point, the existing docs have just been dropped into the correct sections. Index files need to be written as well as perhaps files merged or reworked within sections.

How-tos

How-tos should be each of the learning categories under a howto folder which is visible within the section. This separates the context of reference documentation to more tutorial style steps.

Review *

Below where we say 'review' this relates to writing new index folders, organizing the existing pages into a cohesive structure, how-tos out to individual files and rewriting documentation pages in a standard and agreed upon language style.

We are also looking at using a consistent example across all the documentation and releasing this code on Github so that it gives developers a great reference of what a beautiful SilverStripe project looks like.

Writing and Language notes

Todo

Developer Guide notes

The developer guides are a new concept. Each guide is broken into 2 sections

- How tos (stored within a how-to folder)
- Reference documentation

How-tos should be short, sweet and full of code. The style of these is for users to basically copy and paste to get a solution. An example of this would be How to add a custom action to a GridField row.

Everything else in the developer guide should be written as a reference manual.

Each section should contain an index.md file which summaries the topic, provides the entry level user an introduction guide to the feature and any background then it can go down into more detailed explanation into detailed references.

If you cannot place a how-to within a single developer guide, that would be an indication that it should be a tutorial rather than part of a guide. Tutorials should cover a full working case of a problem, the thought behind the problem and a annotated implementation. An example of a new tutorial would be 'Building a Website without the CMS'. 'Building a contact form' would still sit under 'Forms' as while it may have templates and controllers involved, as a user 'Form' is the action word.

Documentation Tasks

  • Create top level and second level folder structure
  • Move existing documentation into the rough IA
  • Create how-to folders in each learning category to hold how tos, update template to show these on the sidebar
  • Update image paths
  • Set language, writing guidelines and recommendations for consistency
  • Rewrite docs homepage
  • Docviewer improvements
  • 'Review' Getting Started section *
  • Write tutorials for Building a Website Without the CMS
  • Update tutorials and docs for Building a CMS Website to use a standard example (to be available on Github as well)
  • 'Review' Model section
  • 'Review' Templates section
  • 'Review' Controllers section
  • 'Review' Forms section
  • 'Review' Configuration section
  • 'Review' Extending section
  • 'Review' Testing section
  • 'Review' Debugging section
  • 'Review' Performance section
  • 'Review' Security section
  • 'Review' Modules section
  • 'Review' Email section
  • 'Review' Integration & Webservices section
  • 'Review' Search section
  • 'Review' i18n section
  • 'Review' Files section
  • 'Review' Customing the Admin section
  • 'Review' Execution pipeline section
  • 'Review' CLI section
  • 'Review' Cookies and Sessions section
  • 'Review' Upgrading
  • 'Review' Contributing