My experience writing documentation for cloud and software-as-a-service (SaaS) solutions has evolved over time. I spent a good bit of my career documenting large-scale systems and data center operations so I guess you can say that I appreciate playing at scale. The timelines for documentation were generous, review cycles came during the end of the publishing lifecycle, and document delivery took the form of a Word document or Adobe Acrobat PDF file.

Documenting traditional software

I used to follow a framework similar to the following when documenting traditional software:

1. Get access to the application I’m documenting and get my hands on any source material available such as requirements documents, software requirements specifications, and design documents
2. Take some time to work through the application myself without assistance from the developers, product manager, or operations
3. Align my documentation schedule with the overall development schedule
4. Write a first draft of the documentation based on what I can create from self-exploration and research
5. Submit draft for review by SMEs
6. Complete review comments
7. Publish document

Granted I often would customize my documentation processes to meet appropriate organizational staffing and cultural requirements. For example, there have been times in the past I had to put more buffers into my processes because invariably documentation fell down the list of developer priorities but I still had to press on to complete what I could finish on my own,

I’ve written documentation for cloud and SaaS-based customer service, cybersecurity, and backend telecommunications applications. During those projects, I wrote user guides, implementation guides, operations guides, administrator guides, and related content. I spent time believing that developing WebHelp with MadCap Flare was the ideal solution and format for those documents. However, the rise of agile and DevOps made me reconsider because my publishing philosophy began to evolve from technical writer-centric to more team-centric. For example, let’s say a developer needs to swap out some code samples.

In fact, writing technology articles for publication would influence how I document SaaS and cloud applications in the future. I remember when I was freelancing for CNET TechRepublic, I learned how many people turn to Google for help even before vendor documentation. Technical articles fill a significant knowledge gap for some consumer and more technical users alike.

Documenting SaaS or cloud applications

My framework for documenting a SaaS or cloud application right now would follow the same general flow I’ve had success with in the past.

1. Get access to the application I’m documenting and get my hands on any source material available such as requirements documents, software requirements specifications, and design documents
2. Take some time to work through the application myself without assistance from the developers, product manager, or customer success
3. Create a topic-based outline and use a project management tool such as Jira, Trello, or Asana to manage topic development down to editorial checklists and other steps to guide the topic from draft until final
4. Set priorities for the topics to document and develop a publishing and review schedule
5. Work the publishing and review schedule as planned
6. Publish the document and topics on a regular cadence based on updates and revisions.

Mind you such a framework I propose needs to be replicable and supportable by the writing, editing, and subject matter expert (SME) reviewers on the project. I also make it a practice to document the content creation process I’m proposing for a contract or a new job.

Thinking ahead

If I were to document a SaaS platform today, I would look for ways to publish the documentation to Atlassian Confluence or a cloud-based service desk solution. WebHelp and other help formats just don’t lend themselves to iteration in my experience.

Hi! My name is Will Kelly. I’m a technical writer and analyst based in the Washington, DC area. I’ve worked with clients such as NetApp, Dell, and Neustar to develop technical, training, and thought leadership content. My articles have been published by IBM Mobile Business Insights, TechBeacon, CNET TechRepublic, Toolbox.com, ZDNet.com, and others. Follow me on Twitter:@willkelly.