With the upcoming release of our latest SuiteCommerce software — Aconcagua and SuiteCommerce Standard — our technical publications team has been busy not only writing new and updating existing documentation, but also rethinking how it is organized.
One key piece of functionality underlying both Aconcagua and SuiteCommerce Standard is the extensibility API which, now mature, offers new and improved ways to enhance the functionality of your site.
With that in mind, we have reorganized our documentation and refocussed it so that it is more appropriately presented as well as places greater emphasis on using the API for customizations.
Our goal is to create an end-to-end documentation flow that mirrors the business user experience.
Let's take a look at some of the changes we have made.
Split Between User Guides and Developer Docs
On the homepage, you may notice that we've now split the documentation links into two:
With an ever expanding library of documentation, we want to make clear the distinction between the types of tasks we expect site administrators to do and the tasks web developers to do.
In many ways, these changes fit together in two groups: developer docs are more focussed on the SuiteCommerce Advanced product as well as the development of extensions, whereas the the user guides are focused on SuiteCommerce Standard, configuration and site management tools.
New Topic Sections
Under each of these areas are new areas of focus. We've developed new documentation for things like the extensibility API, theming, microsites, marketing and others.
These new topic areas should give you much more specific advice when performing tasks related to these areas of your web store.
Highlighting of Key Areas
If you visit one of the two main documentation areas, you'll see in the sidenav a number of links for the area. I just want to highlight three important ever-present links:
The first two had always been there, but I want to reiterate how important they are.
Firstly, the What's New section is a log, updated weekly by the documentation team, listing the updates, additions, and removals they've made to commerce documentation. It is not a complete list, but it does state the significant changes, so I strongly recommend taking some time every week to take a look. We've put a link on the homepage to remind you.
Secondly, the Release Notes: these are obviously only updated when there's a new release, but there can be a lot of crucial information in them. They are the gospels of what is in a release, so each time a new release is made, you should take a look. You can read about Aconcagua now!
Finally, depending on whether you're in the developer docs or user guides sections, you'll see a link pointing you back to the other. This'll make it easy to jump sections, in case you find yourself lead that way.
Because we're dealing with multiple product lines now, we want to make it absolutely clear when an item of documentation applies to a particular product or release. For example, the SuiteCommerce Web Stores tab below indicates that the documentation is appropriate for all products and releases.
However, it could say, for example, SuiteCommerce Advanced | Aconcagua, to refer specifically to the Aconcagua release for SCA, or Site Management Tools to mean all versions of web stores that use the SMTs.
A new resource on the portal are checklists.
They provide you with prompts and a handy quick reference guide for when you perform certain procedural tasks.
They come in PDF format so you can print them off or just keep them open in your browser to check off items when you complete them.
They're aimed at aiding everyone when doing things like setting up a developer environment, for example. We sometimes get questions from people saying their new developer environment isn't working, when in fact they usually skipped a step during setup, or didn't complete a task completely. This way, you have some short prompts reminding you of the things you need to do (and in the right order, too!).
They're great for new starters who aren't sure what to do, and for old-hands who are, perhaps, prone to over-confidence.
You may have noticed that we have a burgeoning video library. They are produced by our technical publications team and go through some common procedural tasks, such as adding commerce categories in the SMTs.
Note that we have also removed some older training videos that were out of date.
Isolation of SiteBuilder Content
Previously, all of our content was merged together and we talked about Site Builder in the context of SuiteCommerce Advanced. In the reorganisation, the Site Builder documentation has either been separated out or removed.
Anonymous Access to Documentation and Blog Posts
Prior to this reorgnization, we opened up the site fully to anonymous users. This means that you no longer need to log in to view any of our regular documentation, blog posts, or associated content.
A major driving force behind this was so that our site would be open to search engines. We know that a number of users were searching for help related to SuiteCommerce via search engines, and prior to this change it meant that none of our content was been served by them. This was problematic as, naturally, we consider our content to be the most important resource for SuiteCommerce users and developers seeking help with their work.
Now, the vast majority of our content is being indexed by search engines so you should see our content appearing alongside third-party sources. It also means that you can now employ google-fu to narrow down your search on the site, for example:
This Google search will return results for extensibility only from the developer portal.
We're also going to be working on more extensibility tutorials and videos, so that you have a greater understanding of what's possible on the platform.
In the farther future, we're going to look at merging the SMT documentation into the core documentation, as well as documenting business user experience flows. As an example of the latter, if we're talking about item availability, it's often in the context of the records in NetSuite — this change is going to focus a lot more on providing guidance from the experience of the user, from start to finish.
If you have any questions or feedback, feel free to leave them in the comments below.
Posted on Tue, April 3, 2018
by Steve Goldberg filed under