Technically you can: creating technical content for all audiences
How to turn a freight ship around when all you have is a paddle
You have inherited a behemoth of a doc set. The behemoth has grown organically over years, maybe decades. Over the course of its life, technologies have risen and fallen, paradigms have shifted, and writers have come and gone. Your behemoth is a heavyweight cargo freighter, transporting its burden of content in an undefined, and possibly undesirable direction. Users are lost, and all your stakeholders are breathing down your neck to breathe new life into the doc set. Untangle the Gordian knot of fragmented information, and provide lean, user-oriented topics! You have probably already discovered that your doc set is rife with rabbit holes, construction sites and patches of improvement or despair. You know how to write good content. You have bright, fresh ideas. How on earth can you implement them with the sheer quantity of topics on board, and your extremely limited resources and time? You might feel like a passive passenger on your freight ship, with woefully inadequate equipment to steer it where you want to go. This talk presents a structured approach that triggers and sustains an evolution rather than a revolution. I discuss how to identify the right starting points by collecting feedback and hard data from various sources (your stakeholders, traffic stats, support incidents, and knowledge bases). I present a tiered strategy that targets top-level content to deliver quick improvements to users. Resting on agile principles, I also show how to adapt your mindset for this type of endeavour. My approach is based on a current project where my team and I are working to revamp a doc set that has tens of thousands of topics, written over the past 30 years.
OMG, it’s “Error 5”!
How do we know our documentation makes sense?
The Legend of Documentation: A markdown to the past
Decentralised Documentation - Defining standards for an ecosystem
For the past year, I have been working as one of the small number of tech writers in the Ethereum Blockchain space. As an emerging technology that has existed for only a handful of years, engineers are still figuring out what best practices mean to them. Roles such as tech writer, developer relations and support are even more recent hires, in an ecosystem that fluctuates so much. It's near impossible to remain up to date. This has put those of us in these roles in a somewhat unique, challenging, and exciting position where we have been able to define what we think "good" documentation and communication should look like. In this presentation, I share experiences (mine and others) from the past year, and techniques and ideas for those who find themselves as the first tech writer hire in a company, or indeed a new field. The presentation includes:
- Helping engineers identify when projects are too complex
- Creating toolkits and sharing them around an ecosystem
- Cutting through scepticism and hype
- Keeping up to date with constantly changing technology
- Learning from and adapting experiences from other projects
- Funding improvements in developer experience and documentation
- Knowing when a project is no longer active and how to refocus efforts