Hi there. I’m Laurence Simon, one of the technical writers here at cPanel.
Once upon a time, I was like you. I was a technical support representative, in a large hosting environment, who provided support for resellers of cPanel software.
While supporting the customers, I would frequently refer them to the cPanel documentation, but every so often there would be an ambiguity or issue, or something that it just didn’t cover adequately.
For the longest time, I wanted to do something about it, so I packed up my Torani syrups and joined the cPanel Documentation Team last year.
I joined because I respect their philosophy of providing better service to the customers through better documentation, offering as much transparency as possible, and working with a team that has high standards and expectations.
Good documentation reduces frustration for the customer, gets them up and running faster, and reduces support costs. It also educates and empowers the customer so they can focus on running their business, not running their server.
So, how do you create good documentation?
WHAT IS THY BIDDING, MASTER?
The workflow for documentation at cPanel is a well-oiled machine (although we do try to keep the palm oils to a minimum to reduce health risks).
It all begins with a request for a change to the documentation. This can come in through any of the following ways:
Ticket – When a technician takes the time to walk a customer through a process, we leverage that resource and provide it to the rest of our customers who may have a similar issue.
Development scrum team – By assigning technical writers to each of the scrum teams, the writers can be involved in the development process. This allows us to aggressively document pending changes in new features and versions instead of reactive to the changes after they have published. Also, this lets us keep up-to-date with changes in the User Interface so we can direct people to the right locations. Finally, instead of the developers dumping a stack of changes on the writers before the release party, the writers can actually make it to the party, too.
Customer request – If a customer has a difficult time understanding what is in the documentation or has a problem with the text in the user interface, they can submit a request through the Feedback link. Then, we can work with them to make it clearer or provide better examples. We can also add screenshots and diagrams to help customers who think visually.
DETERMINE THE SCOPE OF THE REQUEST
After we receive the initial request, we determine the scope of the requested changes. Usually, we need to make a change to a single document. However, there may be other documents that cover the same subject. We need to make certain that if there are any changes to a procedure or a feature, they are reflected throughout the documentation. Also, if an issue affects multiple versions, we correct that documentation throughout the site.
If a change impacts multiple areas of cPanel & WHM, we can add cross references to the changes in our documentation. These links can go within in the documentation or in an Additional References section.
DIG IN! RESEARCH TIME!
Now that we know where the changes need to be made, it’s time to figure out what we need to change:
Internal developer notes – As our developers work on new features or bug fixes, they write up extensive notes. Or, they add extensive comments in the code, which we can extract and turn into notes. This information gets organized into the new documentation.
Discussion with developers – If anything wasn’t covered by developer notes, or there is a question that needs to be resolved, we can work together to walk through the changed or new feature to catch all the issues a customer might encounter.
Forums posts – Sometimes, a solution to an issue is already available in the forums, and we need to incorporate it into the documentation set.
Tickets – A technician may have already explained or documented an issue in a ticket, but it needs to be incorporated into our public documentation.
PLAYING IN THE SANDBOX
With the scope of the documentation and the raw material in hand, we go to an internal sandbox to work up the new documentation. The sandbox lets us work on documents without affecting the public documentation. It also lets the writers collaborate on documents that may have multiple requested changes in the request queue.
TECHNICAL REVIEW
Once the writers draft up something they’re happy with, they submit it for Technical Review. This is when the technician or developer who originally submitted the request reviews the draft document to make sure that it covers everything that the customer needs to know. Or, if the document came in through a feedback link, a subject matter expert from Technical Support or Development can be tapped to review the document.
PEER REVIEW – YEP, THAT’S A PADDLIN’
Now that we know the document is technically sound and doesn’t contain any rm -rf / gremlins in it, it’s time to send it off to another writer for a Peer Review. Sure, our goal is to follow Global English and our internal style guides, but sometimes we need another set of eyes to catch any inconsistencies or issues. By reviewing each others’ work, we can reduce any grammatical or style errors we may have overlooked. Also, the closer we get to Global English standards, customers can get more accurate translations through machine translation such as Google or Babelfish.
PUBLISH IT
Now that we’ve confirmed that the documentation is technically accurate and is understandable, we can publish it out to the site. This doesn’t just cover the standard documentation out there, but also any necessary updates to the Release Notes and Change Log.
FIESTA DE LA SIX!
Once the document is published on the English side, our Bilingual Technical Writer translates the document. Sometimes during the translation, they may catch an ambiguity or difficult-to-translate phrase that might be better-expressed not only on the Spanish side, but on the English side as well.
MORE FUN TO COME
More improvements are coming to the documentation:
- We’re migrating from the outdated Wiki site to a new CMS engine.
- We’re cleaning up the existing documentation to fit a more stringent internal style guide.
- Also, the Software Development Kit is being overhauled and streamlined to make it easier for developers to build better applications and scripts.
- Finally, we’ll be updating the audio and video tutorials to walk you through the latest features and updated interfaces.
LET’S WORK TOGETHER!
You know, as much as I miss fielding issues in the technical support trenches and solving them, I’m happy to be a part of a documentation team that leverages the hard work of the technicians and developers so that we can keep you, the customer, informed and empowered.
If you see something in the documentation that doesn’t quite sound right or needs clarification, or there’s something we don’t cover yet, just click the “feedback” link and let us know.
cPanel is the greatest webhosting control panel in the industry. Let’s work together to make the documentation the best, too.
