Introducing docs.superoffice.com
Today we're announcing the release of our new documentation service.
Why docs.superoffice.com?
It doesn't matter how good SuperOffice is, if the documentation is no good, people will not use it. Even worse, if the documentation is bad, integrations will be inefficient and not leverage our platform as intended.
Our old content was fragmented and had inconsistent branding, limited searchability, and limited community contribution capabilities. We have consolidated content across 2 community clubs, 6 stand-alone static websites, and several blog and forum posts - all moved to github.com as a content repository and community tool.
The new site is the result of adopting a paradigm shift called Docs as Code, which makes our documentation more sustainable and future-proof. We tap into standardized processes for software engineers, while being open and transparent - because relationships matter.
Key features
The site is both the shell that makes up the destination - where like-minded people go to read about all things technical pertaining to SuperOffice - and the content the website contains. We aim to provide all SuperOffice technical content in one place with a standardized look and feel.
Friendly URLs
The site URLs are structured to be intuitive. That means, for example, when you want to know more information about sales, you can just type 'sale' in the address bar, i.e. docs.superoffice.com/sale, and you will see all information pertaining to sales. If you want to discover more information about documents, you can just type 'document' in the URL, i.e. docs.superoffice.com/document to learn more about documents.
Minimalist design
No muss no fuss! No tonka toy colors, no cartoon figures. Just green and clean! We believe less noise and more information is better than trying to make it look slick and fancy.
Content and site navigation
One key area of investment based on feedback was improvements in site navigation, information architecture, and content organization. For example, we've combined everything from the community technical and developer documentation into a single hub where you can easily discover relevant information pertaining to the topics that interest you.
For example, the following API documentation home page demonstrates our approach at simplying navigation to the various topics within that area. We follow that same pattern throughout the main areas of SuperOffice.
We have raised the existing content into a completely new structure and are constantly revising it. Articles are generally shorter and more focused, being either conceptual, how-to guides, reference, or tutorials. Of course, we can't fix 30 years of documentation overnight. But we're agile and will deliver incremental updates along with new content in the coming months and years.
You can even monitor our progress on Github, and help keep up accountable.
Discovery and search
Instead of multiple disconnected sites with deep content trees, docs.superoffice.com has a solid root you can start exploring from, be it our high-lighted content, based on your role, or popular areas of interest. Our broad and shallow tree will take you to what you're looking for in fewer clicks.
The deeper you drill down, the more details you'll find in the landing pages and table of contents.
For example, the onsite installation landing page showcases main areas of the overall subject, allowing easy access to targeted sections within that topic.
In each section you can filter the table of contents to search a specific term within the table of contents tree.
Or you can use the site-wide search to find exactly what you are looking for.
Continuous delivery
The old pipeline was a mixture of build tools, scripts, custom executables, and duct tape resulting in 7 self-contained websites pertaining to individual technology stacks.
Now, we build using DocFx, an open-source static site generator. All content is version controlled and every change is linked to one or more GitHub issues (work items). This enables us to automatically build the output when new versions of the software are released, with current up-to-date documentation. Yet, we can also easily add new content as it becomes available and fix typos and broken links when needed.
Community contributions
Hosting content on GitHub not only provides us the ability to transparently manage content, but it provides us with a place to point inclined community members to go create issues, provide feedback, monitor that feedback, and even contribute to our content.
You can share a page on Twitter, on Facebook, or via email. Clicking Feedback or Edit will take you to GitHub to either submit feedback or submit an edit for that particular page.
And we have a whole section to help you get started with Markdown, Git, and DocFx:
Practical Implications
What does this mean in the broad scheme of things? All we have done is move the technical documentation and developer documentation out of the community site and combined the content into logical areas of the dedicated documentation site. Unfortunately, hard-coded links from old forum posts will break. The easiest way to locate the linked content is to use our search. Let us know if you have trouble finding something :)
We plan to redirect all traffic from the existing Technical and Developer documentation to the new docs site as soon as Friday, June 25th.
In conclusion
This is just the beginning. Visit docs.superoffice.com today and let us know what you think! And if so inclined, do take advantage of those collaboration features to provide feedback or make suggestions.
See the contribute section on the site for more information.
We hope you find this useful and interesting! Please let us know what you think by providing feedback on our discussion board on the GitHub repository. Go check it out!
Disclaimer: You will need a github account, but the good news is that registration is super simple!
https://github.com/SuperOfficeDocs/feedback/discussions