Posted by Zach Corleissen
Greetings, Mozfolk! My name is Zach, and I'm a technical writer here at SEOmoz.
We've consistently heard from you that Mozscape needs better documentation. I'm pleased to tell you: your requests have been granted! The Mozscape wiki just underwent a thorough update and review by developers, help teamsters, and testers. We incorporated your feedback from help tickets and forums to make Mozscape easier for new users to learn, and more functional for experienced users to reference.
Hopefully this documentation update helps you get the most value from Mozscape. If you haven't taken a look through our documentation yet, we hope it encourages you to see how Mozscape data can help your business grow.
Legacy documentation: a (very) brief history
Like documentation at most startups, the legacy documentation for Mozscape was inconsistent. Not all features were documented; for example, metadata supports a command called index_stats, which returns information about the contents of the current Mozscape Index update. It's been in production for a while, but hasn't been documented until now. (Check it out, it's pretty cool.)
When features changed, sometimes the changes weren't documented. Well-intentioned authors added and edited content in ways that weren’t always comprehensive, followed by other well-intentioned authors who did the same. Not everything made sense, either; the next_update and last_update features of the metadata API return dates for the next scheduled and most recent Mozscape Index updates, but the value returned is in Unix Epoch format, which only makes semi-intuitive sense if you already understand the "Expires" part of signed authentication.
I compare Mozscape legacy documentation to how pearls are formed: created in gradual layers; often valuable; frequently irritating.
With these updates, the Mozscape documentation is definitely on the mend and ready for your viewing pleasure.
What's new (and a new feature)
The What's New page makes it easier to track feature changes in future updates. From now on, any time we add or change features in Mozscape, the change and the date it went live will appear there.
For example: as of May 15th, Mozscape now supports HTTP Secure.
What's different: easier to learn
If you're an SEOmoz PRO user and have never tried Mozscape, now is the perfect time!
Our help team emphasized that we need a better introduction to Mozscape, especially for how Mozscape calls are formed. We responded by streamlining the introduction and improving the way we describe Mozscape’s call anatomy.
What's different: easier to reference
The query parameters are now organized in the way you're actually using them: Scope and Sort together, and Limit and Offset together. We distributed parameters and values specific to each endpoint into their respective articles; for example, possible Scope values for the links endpoint…
…are discrete from the possible values of Scope for the anchor-text endpoint:
Glossary entries are re-pointed to existing (and often better) resources on SEOmoz's main site whenever possible, and we added a few much-needed entries. (How did we get this far without defining target and source URLs?)
What's different: complete parameter value tables
A complete list of parameter values is a big improvement for Mozscape users. For example, the links API accepts the Sort parameter, but the possible values of Sort weren't listed. Also, only some values of the Sort and Scope parameters are compatible. Today's doc update addresses both of these:
What's different: better organization
We're excited to release re-organized topics and reduced duplicate information. An example of all three is free vs. paid access to Mozscape. Here's what it looked like before:
.png)
Here's what it looks like with one of the most-requested features: a side-by-side comparison of free versus paid access to Mozscape.
The legacy documentation referred to different “versions” of Mozscape for free and paid users. This isn't technically accurate, as there's only one version of Mozscape with different access tiers. Also: notice the cleaner fonts and layout? Our awesome UI guy, Kenny brought the API wiki in line with our site-wide standards.
Best Practices is a single article now. It used to be a category:
Most of the "best practices" in the legacy documentation weren't best practices per se; they were required practices. For example: there's no way to use Mozscape without signed authentication, making it a practice that's "required" rather than "best." With the update, Best Practices now lives up to its name with value-adding information about batching calls and maximizing your value by making requests in parallel.
What's different: less information?
Our users are pretty hardcore (a good thing!), so you may notice that two or three topics now contain less information than previously. For example, some response fields were listed as being "for internal use and subject to change".
If a response field can only be generated from an internal call, there's no reason to expose it to users, so we removed them from the documentation…and it would be a rare feature indeed that wasn't subject to change.
I know what you might be saying. "But less information is less transparent! Less transparent is less TAGFEE!"
That's true; transparency is critical for good documentation. When it comes to user guides, though, more does not always mean better. TAGFEE also means empathy; if extraneous details make it harder to learn Mozscape, then the documentation lacks empathy, and that's bad. We're striving for the right balance between abundant information (transparency) and providing knowledge that will actually help you (empathy). Mozscape is awesome, and we want it to be as valuable for you as possible.
Closing with a question
How can we keep improving Mozscape documentation? Please let us know in the comments!
Sign up for The Moz Top 10, a semimonthly mailer updating you on the top ten hottest pieces of SEO news, tips, and rad links uncovered by the Moz team. Think of it as your exclusive digest of stuff you don’t have time to hunt down but want to read!