During the recent Wellington hackfest and online via the SilverStripe developers mailing list we started the process of working on a relaunch of doc.silverstripe.org and drafting what that looks like going forward.
From discussions throughout the community, a number of common issues with the current documentation have been boiled down and drafted up into a plan for a reprise of the documentation for SilverStripe. The actions we are following are available to view on our public documentation trello board and consists of the following key activities.
Robust information architecture (IA)
At present, there is unnecessary confusion from the labeling on the site and categorisation of the pages. A few examples include Topics vs Reference, a Misc category and digging into those categories reveals no second level structure to help you narrow down what you are looking for.
The hackfest team of community members quickly prototyped ideas with post-it notes on a whiteboard and ran a quick sorting exercise with both the current documentation and the pending requests for more documentation on GitHub to test the categorisation. We think we’ve come up with a pretty robust IA which will make things clearer for users and developers, and allow contributors to see what is missing from the documentation to encourage improvements.
The post-it prototype quickly went from the whiteboard to a pilot restructure of our documentation markdown which can be viewed online. Note that this repository is a work in process. The currently existing content has been restructured but not rewritten with respect to our proposed new IA so use at your own discretion (and please submit any new documentation to the official SIlverStripe repository).
Exact wording of specific sections has not been formalised and the specific guides available may evolve but conceptually we think this IA is a great step forward for ease of use.
The three main sections are as follows:
Getting Started
Includes everything to get a user up to the level of having SilverStripe running and being able to access the CMS.
This section will include items like server requirements, local development installation on various OS and installation on a server among others. This should be a precursor to any tutorial and likely the first documentation that users jump into.
Tutorials
Tutorials remain generally in the same structure and we’ll likely rewrite them to use a common example project spread across the entire docs website (more on that later). Learning will still cover basics of a CMS website with Page Types, Forms and DataObjects at a high level. Penciled in is at least 1 new tutorial, ‘Building a site without the CMS’.
Developer Guides
Topics and Reference are gone. Replaced by the Developer Guides section (working title).
Each guide is focused around a topic such as Models, Testing and Security to name a few. Topics will have a basic introduction then break down into reference material and specific how-to code examples. Long winded documentation pages will be logically broken up into more manageable pages with an improved user interface for moving sequentially through a section of the guides available.
How-tos will be displayed alongside guide content on the topic home page enabling users to jump quickly to code samples. This has the benefit of keeping the reference documentation more concise while making useful code snippets easier to surface. How-to content will also be included in the master documentation Github project as reference.
A rough idea of what it might look like from an IA point of view for say the "Templates" Developer Guide.
-
Navigate to "Templates > Introduction" (~3 paragraph introduction with contextual links about the feature).
-
Introduction includes links with a summary of each of the reference sections (e.g. "Template syntax") and separate links to each of the how-tos (e.g. How to build a navigation menu or How to build a paginated list).
One of the major issues with the current documentation is that after the current set of tutorials, the steps for progressing onwards and growing your knowledge of SilverStripe is not clear. Our hope is the developer guides IA will provide that logical extension to a users learning after completing the tutorials and fill in the blanks that the tutorials leave behind.
The following wireframe may give you an idea of what a typical guide section introduction page may end up being laid out like not to mention that the final look and feel will likely follow on from the design and styles being created for the silverstripe.org relaunch.
Consistent example reference project throughout
As mentioned briefly previously, we want to update all the documentation to use consistent language and ideally extend this to the code examples too with a consistent example project acting as a model of how to build websites and applications using SilverStripe Framework and CMS. This will help users build an understanding of an entire lifecycle of an application within SilverStripe rather than arbitrary situations for each particular guide.
Pushing this project to Github will provide a concrete example of what a SilverStripe project should look like including how to write more complex, custom code and working with testing. We are also hoping that having this code available in open-source will also foster greater contributions to documentation and how-to code examples.
New documentation
The updated IA and card sorting exercise has shown where we need to focus our new documentation efforts. In reality we don’t have resource within the core developers group to completely rewrite the documentation or add everything we want right away (community help is always appreciated). The initial focus is to work on restructuring the original content to the new IA, updating page content to use consistent language and approach and then finally look at areas such as the dependency injector and custom controllers which have been requested by the community as areas currently lacking.
Docviewer module improvements
In part to facilitate the IA changes and in other part to make user experience better the software powering the documentation site (the SilverStripe docviewer module) will undergo several enhancements, culminating in a 1.0 release. These improvements are listed on the module's Github milestone page.
Next Steps
We’d love to get your input and help on making the documentation better. Everything you need to get up and running with doc.silverstripe.org is available publicly on the SilverStripe Github page and the current home for the docs rewrite markdown content is on my own fork of the SIlverStripe Framework along with a TODO list.
The Trello board is available to see progress of the project as a whole. If you would like to contribute time and effort please get in touch with myself or Cam (SilverStripe's Community Awesomeness Manager) and we’ll coordinate efforts for the documentation taskforce.
