Writing for Software
Earlier this year, I began transitioning from writing content for Epicor HCM to Prophet 21 application. The more I read up on Prophet 21, the more I realized it was a very different application than what I was used to. So, I treated it like I would any other writing project—I asked questions, built on my existing knowledge, clarified expectations, began my first project, asked more questions, and so on.
Anytime I start a new writing project, I’m reminded of the writing process taught in school: planning/pre-writing, drafting, revising, editing, and publishing. While we often think of this as a method of teaching students to write, the truth of the matter is, whether starting a new project or being brought into an existing project, writing for software isn’t much different.
Planning – When starting any new project the first step is building a strong foundation. Develop relationships with the people already involved with the product, establish lines of communication, and use the existing resources, including the training courses, documentation, and people, to learn all that you can about the project and subject matter.
Once you have that foundation, identify any standards and styles already in place before building the content. This may require additional research – review style guides and ask questions of the subject matter experts.
With software, planning also includes going through the steps and processes within the system, determining how they all work together, and then deciding which type of document best meets the needs of the audience. Consider creating an outline to ensure that all bases are covered.
Drafting – Drafting begins when you take all of your preparation and planning and begin writing the content. As you write, there is a good chance that you’ll need to go back and do additional research – ask more questions of the subject matter experts, and write as you rework your way through the steps and software processes.
Revising – Review your content, pay close attention to the style and structure. Test any instructional steps in the document. Then make any changes as needed, such as adding additional information, rearranging steps and information, and removing or replacing any content that doesn’t work.
Editing – Proofread your documentation for grammar, then ask subject matter experts to complete a review of both the content and the overall cohesiveness of your document. Once everything is said and done, you likely need to make a few changes, apply a handful of final quick edits, and do a bit of cleanup.
Publish – The final step for writing for software is getting you documentation into the hands of your end users. Depending on the document type, this might be publishing online help to the software system or uploading supporting documents to your company or product website.
Starting a new writing project can sometimes be intimidating. But by breaking your project out into the five basic steps of the writing process, it doesn’t have to be.
Posted By Christine Stretton, Content Specialist, Epicor University