-
Notifications
You must be signed in to change notification settings - Fork 0
content dev process
| If you attend a daily standup | If no daily standup |
|---|---|
|
- Go through the bugs mentioned in the standup to verify if they impact documentation. - Prioritize the rest of the day by working on sprint work items. - Work with the PMs and Devs on what the impacts are and document them. - Continuously conduct audits of existing content to identify areas for improvement. This could be editing for clarity, fixing spelling and grammar issues, and verifying the accuracy and completeness of the content. - Address ad-hoc issues as they come up. This could be addressing a newly discovered bug with the PM to discuss the wording for the UI or user guide or both. This can take up most of my day because a lot of the ad-hoc issues are unplanned sprint work items. |
- Prioritize your day by working sprint work items. Complete at least two tasks/action items per day, but the goal is to complete three per day. - Continuously conduct audits of existing content to identify areas for improvement. This could be editing for clarity, fixing spelling and grammar issues, and verifying the accuracy and completeness of the content. - Address ad-hoc issues as they come up. This could be addressing a newly discovered bug with the PM to discuss the wording for the UI or user guide or both. This can take up most of my day because a lot of the ad-hoc issues are unplanned sprint work items. |
This phase is where you'll do most of your work. You'll find out more about the user's needs, their journey, what they expect, and what they require. You'll also learn more about the product to help define what's needed in terms of product documentation.
-
Gather existing information—any or all of it. Ask questions if you don't understand. Remember, you're creating content that helps create a good experience for the user when using your product or service. You're helping them along their journey!
-
User needs come first: Research what your user wants and needs. It can be user research, usability research, expert research, or any kind of research with data and evidence of what the user wants and needs.
-
Give them what they need when they need it: We know that giving people information too early or in the wrong place can make people leave in frustration and no longer trust you. Understanding what your user needs – when they need it – can be the difference between success and failure.
-
In the way they expect it: Use the language your users are using. You don't use language for search engines – you use it for the humans behind those engines. You don't pull people into useless pages. Instead, you help people. Language used in a product must reflect your user's vocabulary, or they may find the interaction too difficult and eventually abandon it.
In the end, once you have a better understanding of the user journey, you'll have a complete picture of what kind of content your user needs at each step of their journey.
-
-
Determine what documents and other information will need to be created. If, at the very least, you'll need product descriptions upfront. Why? Before you can decide what document types to deliver, you'll need to have a full understanding of the product. What does it do? What's the purpose and why would anyone want to use it? Do you thoroughly understand the product descriptions? If you don't, then the user won't. The next thing you'll need to understand is the user journey. What does the user journey look like with this product? Are they consumers (for example, mobile devices) or are they enterprise users? This also helps you determine what you need to deliver in the end.
A misconception that I've seen about deliverables is that you can take all the content from a user guide and reformat it, let's say, in a PowerPoint for training material (or a training guide). This is, in my opinion, the wrong approach because each guide has a purpose. A user guide helps someone perform a task. A user guide is meant for reference and self-serve assistance. A training guide is more structured because it helps someone learn about the product and how to use it using scenarios. That's a big difference between the two: user guides are written to assist and give guidance while training guides are written using "real-world" examples. If you determine you want a user guide and a training guide, make sure you clearly understand the format for each of these documents. The user guide can then be used during the training as their reference guide.
This phase is an iterative phase where you work closely with the SME, Product Managers, Marketing, and any other knowledgeable person. Here you'll, do the Initial interview with SMEs -> Write -> Review -> Update -> Review -> and the cycle continues until the content is approved. I say content because technical writing focuses on module writing; in chunks of information that can stand on its own as a topic or be integrated into a bigger document. This "chunking" of content is the Minimalism approach. Minimalism is an art, and just like Content Design, it's a way of thinking. Think like the user.
Like the writing phase, this phase has an iterative approach. Today, the content is online and most commonly integrated into the release pipeline. You'll deliver content that is aligned with the items of a particular Sprint. This is where using minimalism to write the content in smaller chunks works because in a sprint you're focused on one user story of the product feature. You're not focused on writing an entire guide from end-to-end, you're focused on sections of it. It's still the iterative approach
Depending on your organization, there might be controls and mechanisms in place that require a lot of check-offs before publishing the content. For example, Microsoft docs has a bunch of workflows built into GitHub so when you create a pull request for merging, the workflows trigger the checks and balances that they configured. One trigger is Acrolinx, which checks the Microsoft style guide, voice and tone, and even formatting. If the score comes back below 80%, the content cannot be published until fixed. This is just one example of controls and mechanisms behind the scenes that are required before publishing. Check your organization. It may be that your marketing team needs to sign off on the content before it's published.
This phase is ongoing. It's the one thing I've seen a lot of technical writers neglect. What do I really mean by the "maintenance" phase? It means keeping your documents fresh and up to date. Just because it's delivered doesn't mean you can't go back in and make clarifications on something. I've often found when I've gone back to a topic that I finished I notice things that can be improved. For example, I might see a paragraph that isn't that easy to scan so I'll rework it so it's either in a table or bullet list. Something that'll make the content easier to scan and read. Remember, readers scan; they don't read.
Today, archiving older versions is done digitally. For example, I use Docusaurus for my content and I can implement versioning where I can retain older versions and allow the user to select the version they want. Plus, professionally done technical content is always integrated into a version control system like GitHub or other CMS for DITA projects.