Documentation is not usually a favorite, or let’s say popular topic. Well, except for me and my friends. But in the world of apps, APIs, and integration it's a necessary evil. No matter how well designed an API might be, you're still going to need to know what MIME type is required in a response or just what the heck an attribute actually means. But rather than blather about the inherent value of documentation, instead we'd like to tell you a bit about our new Help Center and why we made the change. For those of you who really hate reading (tl;dr), at least take a minute to check out our new Help Center.
Why we decided to change
As we looked at ways to improve our documentation, we narrowed down to three main goals: simplify, provide different voices and perspectives, and make sure you had the right information, in the right place, and at the right time. We looked at our documentation landscape and decided to change from a Developer Portal and separate Knowledgebase, and move to a single, integrated Help Center with improved in-app guidance.
Integrations are hard, and while Cloud Elements makes them easier, it remains a complex platform to document. To cover the information, we stood up the Developer Portal that contained both instructions and reference information. Over time, we realized that the prescriptive approach to the documentation in the Developer Portal didn't meet all of our customer's needs. So we went to the front lines of information and asked our customer success team to write Knowledgebase articles for common questions. While the technical writer could write broad, happy-path content, the customer success team could provide deep dives in real world situations.
Great idea right? But there was a small problem. The Developer Portal is powered by markdown files, the Jekyll static site generator, and a Docs like Code workflow. This was a great setup when the contributors were mostly developers. But as the customer success team became primary contributors and developers got, well, super busy, it presented enough of a roadblock that important information remained tribal instead of shared. The easiest way around the roadblock was to give the content creators a much more user-friendly authoring environment. With no more barriers, the team contributed nearly a hundred new Knowledgebase articles in just a few months.
Wow, another great idea, right? But now what happens when you need more details than a Knowledgebase article provides? What if you come to the Developer Portal looking for a specific question not answered there, but that is answered in the Knowledgebase? Asking you, our awesome customers, to search in two places was a little much. It became clear that we had to unify the Developer Portal and Knowledgebase in a single, searchable Help Center. And we had to do it in a way to encourage passionate contribution from all of the super smart Cloudies possible.
So now all of our technical content is under one roof. We've tried to make searching as easy as possible. We use a faceted search, so you can filter your search results by category.
Providing information where you need it
You might have noticed recent feature announcements appear when you first log in. We're constantly releasing new features and enhancements and want to make sure that you're kept in
the loop. Accompanying those announcements we've added walkthroughs to provide guidance without the context switching associated with leaving the software for documentation.Another goal was to make information more accessible. We know it can be difficult to look up information or instructions while performing an already demanding task. So we're looking at ways to bring much of the how-to content from the Developer Portal to Cloud Elements 2.0. One way is by adding walkthroughs and in-app announcements.
We designed the walkthroughs to be short, informative, and direct. We're not going to waste your time with these walkthroughs. We want to point in the right direction and give you enough guidance to get started.
This type of user assistance is great for those configuration tasks you need to do every once in awhile. You don't need to waste precious memory banks on infrequent tasks. We'll also use walkthroughs to introduce you to a new workflow like the one you'll find on the new Instance page. Lastly, you can use walkthroughs to just get you started on something you're completely familiar with, but just can't quite recall where to start.
The next time you're in Cloud Elements 2.0, look for the walkthrough icons. It's a treasure hunt. Check them out and let us know what you think.
Congratulations! You made it to the end
….or maybe you just scrolled to the gold nuggets at the end. Either way, we'd really like to hear from you on our changes. This remains a work in progress. We have many walkthroughs to write (suggestions?) and still need to implement some plans for the API reference content (again, suggestions?).
Please send your feedback, questions, comments, criticisms, and favorite limericks, puns, or haiku to firstname.lastname@example.org.