Help Engineers Write Better: Tools for Enterprise Content

Elly Searle, of CrowdStrike, walks us through practices to help non-writers contribute better content.

People use your product to do their jobs. There's a difference between a "productivity" application and a "consumer" application. Also, the person buying an application, especially at the enterprise level, is not likely to be the people using the application. Harder to get metrics on words in enterprise products.

Often the amount of words being developed is too much for a (usually small) writing staff. So engineers are writing especially field names and descriptions and errors.

You want to identify opportunities for developers to write better. Is there something we can help them with. For example, find places where similar things are written, patterns. Then find a consensus that better writing would help user.

Partner with people, managers, leads, etc. who have social capital and who support better writing. Have supporters make the invites, and then talk up the training. Data on how current content doesn't meet user needs is important. Figure out how to get before and after metrics.

Really important to understand developers' workflow. What tools do they use. Shadow them if you can. Put the resources you develop on their wiki, or wherever they have their resources. Show, don't tell. Show them the before and after. Teach actionable writing guidelines. Workshops should contain exercises. Then audit output afterwards. See if the practices take hold.

Create templates for the different types of content that developers would create. Include information about how users use that information.

Audit existing content. Identify content that's written well and show why it works, in addition to finding the content that doesn't work well. Identify what is and is not consistent.

Create a curated word list. You will find lots of disagreements about words. Define words. Explain why consistency is important. Explain words choices.