Frequently Asked Questions (FAQ)
Documents are familiar to us all. Think of things like user manuals, reference charts and brochures. They may be printed, or in an electronic file format like Adobe PDF and Microsoft DOC – formats which are discrete, linear, static and hard to maintain effectively, yet undoubtedly in demand and valuable when done well.
Content is perhaps harder to define, but hints at many more possibilities.
At the small scale, you can think of ‘content’ as the building blocks – all the ‘pieces’ of meaningful information that we create and put together to form the substance of our communications, rather than the manner of its presentation. The text, diagrams, videos and other informative data (and even user comments) that go into a document, blog, help application, e-learning module, web portal or knowledge base.
With the right tools, content can be assembled into many different documents and other outputs. A document is really just one way of structuring, presenting and sharing a selection of content.
At the large scale, ‘content’ is often also used as a collective term for all of the above. When someone refers to content strategy for example, they usually mean planning, development, and management of varied informative media across an organisation or part of an organisation.
Note that being new to a particular domain is not necessarily a drawback in a technical writer; starting from scratch can help a writer see things through the eyes of the intended audience. Good technical writers are able to inwardly observe their own learning process and draw on this as a resource. Then they can better predict what the intended user will need and ask the right questions to develop content which fills the gaps effectively. Technical writers act as advocates for the end-user.
In the course of their work technical writers often get ‘hands on’ with your product. As a result, they can often provide valuable contributions for testing and improving software/hardware/processes.
And, integrating a technical writer into your project early can help you to optimise decisions. Technical writers often provide insight you can use to avoid unnecessary cost, risk and complexity in both your documentation and your product.
You should look elsewhere for serious graphic design work or technical illustration. Or, depending on the nature of the project, I may be able to sub-contract these elements for inclusion within the final deliverables.
Being able to quickly understand unfamiliar software and technology (and explain it to others) is central to what I do. So I’m pretty handy with software in general. However, the main technical writing tools I use at the moment include:
- MadCap Flare and other tools in the MadPak suite
- Visual Studio Code, Git and Antora (a static site generator for Asciidoc)
- Microsoft Word and other products in the Microsoft Office/Office 365 suite
- Oxygen XML Author (for structured authoring with DITA)
- Adobe Acrobat Pro DC
Some enterprise class tools that I am fluent with include:
- Ixiasoft DITA CMS
- Jorsek easyDITA
- Atlassian Confluence, JIRA and BitBucket
- Microsoft SharePoint
I use best practices to secure business data, including:
- Encrypted, automated daily backup — to both local and off-site storage
- Strong passwords, encrypted storage devices, multi-factor authentication wherever it is available for services
- Virtual private network (VPN) connection for untrusted networks
- Keep antivirus and other software up to date
Wherever you need technical concepts, tasks and reference information to be communicated clearly, I can help.
For example, some of the most common forms of documentation I might help you with include:
- user manuals
- administration manuals
- knowledge bases
- blog articles
- release notes
- quick start guides
- quick reference sheets
- contextual help
- installation guides
- integration guides
- configuration guides
- troubleshooting guides
- programming guides
- system descriptions
On the other hand, weak documentation costs. A lot. Your experts have a vital part to play, but foisting documentation entirely onto your development team is bad for morale and productivity; quality issues delay your time to market; sales are harder to win; support costs are higher than they need to be; you get bad-mouthed by frustrated users.
I can help you turn your users and customers into devoted fans. After all, there is no marketing like word-of-mouth from your own army of evangelists.
And, having me on board takes the load off of you and your team so you can focus on your core tasks.