Tim Gulliver-Haynes, Documentation Manager at GOSS, outlines recent changes to the documentation website.
It's always nerve wracking launching a new website, but I think a relaunch that includes a new design, and involves manually combining the contents of four websites into one without taking anything offline might be worse. But that is exactly what happened to this site in the middle of January. This article explains what's changed and why, and reveals some plans for the future.
Before looking at what has changed I first want to thank everyone who contributes to and gives feedback on the documentation - you help make it what it is. I hope that with the new site structure, the planned rewrites, and new content, documentation at GOSS will continue to go from strength to strength.
So what was up with the old docs?
I'm not going to go into the history of our documentation (there is a PowerPoint if anyone is interested), but in short, we ended up with seven subsites covering four versions of iCM, product documentation, and a knowledge base which had a bit of everything in it. It's not hard to see how the documentation was starting to become fragmented.
While there was a single search that covered all of the subsites, with facets to help make sense of the results, it was quite easy to find yourself down a rabbit hole of technical documentation, while the example describing exactly what you needed was over in the knowledge base. Articles started to become littered with links between the various types of documentation, when what we really needed was all of the documentation for a topic in the same place. So that's what's happened.
Oh, and for anyone wondering about four versions of the core iCM documentation. We used to have dedicated sites for each patch release of iCM (versions 10.0.5.0, 10.0.6.0 etc). With the move to continuous platform updates we now have one set of iCM documentation, which is kept up to date with each release.
What has changed?
One site
The most important thing to note is that we now have one site, docs.gossinteractive.com. All of the content from the previous sites is now on this domain. I've tried to keep all of the friendly URLs the same, for example, the old frameworks.gossinteractive.com/casemanagement is now at docs.gossinteractive.com/casemanagement.
New structure
The divide between how to use iCM as a content management system and the website that appears at the other end has gone. You'll now find articles about articles, and information about themes and site features, all in the same place.
The same is true for APIs and articles explaining concepts, conventions and examples. For example, in the History Service section all of the content from knowledge base is now alongside the API documentation.
Key product documentation can hopefully be found more easily. The various types of Bookings are now in one place, Case Management is top-level documentation rather than sitting alongside website templates, and there's a new section dedicated to the Tools and Expansions used to manage your platform.
The Release Notes now use a faceted search, ordered my most recent release. The notes have also become a lot more detailed, with the Framework 18 release showing the new style that will be used across products.
Future plans
There's still a lot to do!
One of the biggest items at the top of the list is to review the forms and workflow documentation, and to update all of the examples. While there's nothing "wrong" in the existing content, some of the forms are several years old and don't make the most of recent updates that make designing forms and building workflows easier.
I'm very aware that the website Theme Documentation pages aren't good enough. The style reads like a specification document, describing what a theme looks like and how it behaves, when what would be really useful is some step-by-step guidance on how to build a great website.
We need better documentation on data management within the platform. There is information covering data in Self and Assisted Service, conventions in history, and Case Management history records, but it's still fragmented and doesn't really help you to decide where you might want to store data when building your own services.
Finally the release notes probably only cover around half of our products. Release notes for everything will appear as product updates roll around.
Thanks
That's enough to keep me busy for a while. As always, get in touch via Slack or the feedback bar on the site with any comments or suggestions (or even problems).
Tim
Share this page
