Tech writing workflow

[practicalli-johnny]

Integrating with software development workflow

Initial Analysis

What stakeholders are involves

• producers of content
• consumers of content

Scope of stakeholders
-internal teams

• external customers
• technical awareness

identify which existing documents need changes and see how much new content will be needed

writers should not face short and desperate deadlines anymore just because the team remembered about documentation just before a release

Design

Work closely with development teams understand the impact of change

technical writers review if changes or improvements to the way information is communicated, what’s the ideal user journey,

• what type of content is needed
• how best to integrate with existing content

Implementation

A continuous communication should already be established between all stake holders and especially engineering and tech writing roles.

Information should be communicated incrementally to ensure important information is not lost or forgotten

Communication of implementation details as they are being worked on make the process of capturing documentation very effective

Some aspects of the implementation may change but it is easier to modify the docs at the time of change and less of a risk that information is missed

Testing

Testing of the technical writing should be continuous as with unit testing code.

Content will naturally got through many iterations as understand grows, both of the aspect being created and how to meaningfully communicate the new

Linters and CI tools that build and deploy new content should be run at least locally to establish a baseline quality and ensure there are no challenges deployed changes in content

Stakeholders from different areas may have different levels of engagement

• engineering has lots of 2 way Comms
• external customers may have access to pre-release (staging) content or receive snapshot release, especially if there are breaking changes or potential service downtime
• internal customer relations can act as reviews before passing new content on to customers, especially if change has to be managed carefully
• know your customer initiatives will help unveil the level of Comms a customer will balue

Release

Both documentation and code are released together.

When documentation is not treated as an afterthought, documentation is highly effective comprehensive and written with the relevant stakeholders in mind.

Maintenance

When docs or code issues arise or are reported then doc changes should always be considered as part of the solution