From 79e9254f057f7840d0256e2d2b720a87dd76bce5 Mon Sep 17 00:00:00 2001 From: Will Rossiter Date: Wed, 23 Jul 2014 19:49:47 +1200 Subject: [PATCH] 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 --- docs/en/03_Upgrading/00_Upgrading.md | 41 ------------ docs/en/README.md | 96 ++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 41 deletions(-) delete mode 100644 docs/en/03_Upgrading/00_Upgrading.md create mode 100644 docs/en/README.md diff --git a/docs/en/03_Upgrading/00_Upgrading.md b/docs/en/03_Upgrading/00_Upgrading.md deleted file mode 100644 index d5c99eec4..000000000 --- a/docs/en/03_Upgrading/00_Upgrading.md +++ /dev/null @@ -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. - -
- Never update a website on the live server without trying it on a development copy first. -
- - -## 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) diff --git a/docs/en/README.md b/docs/en/README.md new file mode 100644 index 000000000..d6ac3a8c0 --- /dev/null +++ b/docs/en/README.md @@ -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 \ No newline at end of file