Write the Docs – Decentralized documentation by Chris Ward
Catherine Heath | June 3, 2019
Chris Ward is freelance technical communicator based in Berlin. He gave a talk at Write the Docs Vilnius on decentralized documentation for blockchain, and defining standards for an emerging ecosystem.
Blockchain is nothing if not controversial. It can be considered a scam, or it can be empowering technology. You can use it to track identity, defeat fraud, and empower people to have bank accounts where they otherwise wouldn't be available.
The Ethereum Foundation
Chris works with the Ethereum Foundation, which develops a technology that allows people to run computing applications on the same infrastructure.
Blockchain is about decentralisation, and the Ethereum Foundation is decentralised. This leads to communication issues, as you can imagine.
Many projects in the Ethereum space are open source, and rely on code contributions from the general community. Unfortunately, they realized that no one really understood how to use the technologies, and they needed a technical writer to help explain them. This is where Chris came in.
Chris has fallen into a lot of new work in this way, and he also works on a project called Solidity.
The Hype Cycle
One of the first challenges with blockchain is getting through the hype, skepticism, and misinformation to find what really matters. Chris mentioned the Gartner Hype Cycle:
Image source: Gartner
When it comes to technology, hype goes through several phases. These include:
- Innovation Trigger
- Peak of Inflated Expectations
- Trough of Disillusionment
- Slope of Enlightenment
- Plateau of Productivity
Blockchain is going through this cycle at the moment, according to Gartner, and it's currently just passing the Peak of Inflated Expectations. The future of blockchain is therefore the Trough of Disillusionment.
Learning new technologies
Technology is defined by constant change, until it stops. Your documentation involves a lot of rewriting as the way you use a technology changes. It's addictive to constantly discover the latest thing, but also exhausting and frustrating.
Chris shares tips on how to prioritize learning new technologies:
- What is relevant to you
- What is relevant to who you write for
- A feature or an experiment, or will it actually be delivered
- Is this one person's idea, or a team idea
This is great advice on how to choose which new technologies to learn for all technical writers.
Managing competing stakeholders
You need to consider different stakeholders as a technical writer in the Ethereum space. This includes developers, users, and token holders. Token holders are people who actually own tokens associated with a particular bitcoin technology, and they are like the equivalent of shareholders.
Token holders often have more influence over a project than anyone else. Token holders can be a big distraction to the technical project underneath.
Often community managers are just dealing with token holders. It's addictive to follow the changing values of tokens and try to make profit out of them. Chris finds the constant discussions of value to be distracting.
All the bitcoin projects are run by engineers and there are no project managers, which can lead to projects being overly technical. Technical writers are in a position to ask whether projects are actually useful, rather than just an engineer's passion project.
Reinventing the wheel
On the one hand, it doesn't make sense to "reinvent the wheel" when it comes to technology. And yet egos can get in the way of this fundamental design principle. People constantly want to reinvent the "best" wheel, but this impacts the developer experience of your product. Having five different options can be overwhelming for the people you want to adopt the product.
It's also a challenge to know when your project is going to be useful, what are the different use cases. Chris recommends learning from the giants, since the technologies underlying blockchain have been in use for a long time.
The blockchain community
It's a new community with a lot of opportunity for growth. Getting involved in large, old, open source projects can be daunting, because many people have been involved for years. You can determine what is the best way to do things in a new open source project, and have a lot of influence over the future of the project.
In Ethereum, the writer of the technical content always owns the content (since it is managed using blockchain technology). Companies also commission content on a platform called Gitcoin. The work is compensated, but it happens through GitHub and uses pull requests.
It can be hard to get your head around new technologies like blockchain, but Chris talked a lot about how exciting it can be to become involved in this space. There is a need for more technical writers to document products like Ethereum, so it could be worth developing your knowledge of blockchain.