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
This commit is contained in:
Will Rossiter 2014-07-23 19:49:47 +12:00 committed by Cam Findlay
parent 6c5ddaf054
commit 015afe83e8
2 changed files with 96 additions and 41 deletions

View File

@ -1,41 +0,0 @@
# Upgrading
Usually an update or upgrade to your SilverStripe installation just means
overwriting files and updating your database-schema.
See our [upgrade notes and changelogs](/changelogs) for release-specific information.
## Process
* Check if any modules (e.g. blog or forum) in your installation are incompatible and need to be upgraded as well
* Backup your database content
* Backup your webroot files
* Download the new release and uncompress it to a temporary folder
* Leave custom folders like *mysite* or *themes* in place.
* Identify system folders in your webroot (`cms`, `framework`, `sapphire` and any additional modules).
* Delete existing system folders (or move them outside of your webroot)
* Extract and replace system folders from your download (Deleting instead of "copying over" existing folders ensures that files removed from the new SilverStripe release are not persisting in your installation)
* Visit http://localhost/dev/build/?flush=1 to rebuild the website database
* Check if you need to adapt your code to changed PHP APIs
* Check if you have overwritten any core templates or styles which might need an update
* See [common-problems](common-problems) for a list of likely mistakes that could happen during an upgrade.
<div class="warning" markdown="1">
Never update a website on the live server without trying it on a development copy first.
</div>
## Decision Helpers
How easy will it be to update my project? It's a fair question, and sometimes a difficult one to answer.
* "Micro" releases (x.y.z) are explicitly backwards compatible, "minor" and "major" releases can deprecate features and change APIs (see our [/misc/release-process](release process) for details)
* If you've made custom branches of SilverStripe core, or any thirdparty module, it's going to be harder to upgrade.
* The more custom features you have, the harder it will be to upgrade. You will have to re-test all of those features, and adapt to API changes in core.
* Customisations of a well defined type - such as custom page types or custom blog widgets - are going to be easier to upgrade than customisations that modify deep system internals like rewriting SQL queries.
## Related
* [Release Announcements](http://groups.google.com/group/silverstripe-announce/)
* [Blog posts about releases on silverstripe.org](http://silverstripe.org/blog/tag/release)
* [/misc/release-process](Release Process)

96
docs/en/README.md Normal file
View File

@ -0,0 +1,96 @@
# 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
- [x] Create top level and second level folder structure
- [x] 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