Episode 8: Writing Good Documentation with Chris Ward

Sponsors

Gitlab Commit

Adventures in DevOps Podcast

The DevEd Podcast

Cachefly

Panel

Richard Littauer



Joined By Special Guest: Chris Ward
Episode Summary

This week, Sustain Our Software welcomes Chris Ward, Technical
Writer at Ethereum from Berlin, Germany. Chris shares his story
of how he became a technical writer as well tips and resources
for good documentation writing.


After many years working as a developer, Chris realized he
enjoyed helping others understand technical subjects. Chris
defines a path of how to become a technical writer. He advises
contributing to Open Source projects as well as joining
the Write the Docs Society.


Chris and Richard discuss why having good documentation is
important and what the minimum viable documentation for a project
is. Often times the assumptions that developers make are not very
obvious to other developers on the project and the users.


Then then discuss the common challenges a technical writer faces
when creating documentation targeting developers, contributors
and Getting Started Guide. A good technical documentation
develops over time and like code it's never really done and newer
versions are rolled out as questions come in.


Chris recommends some tools for technical writing as well as a
book by Stephen King called On Writing. He also recommends
dogfooding or hackathons to help the developers work on usability
issues.


Then they talk about how the Bounties model can also be applied
to documentation writing.
Links

Learn to Build on Ethereum with Kauri

https://readthedocs.org/

https://github.com/btford/write-good/

Society for Technical Communication

https://www.ethereum.org/

Write the Docs Society

https://gitcoin.co/

On Writing

https://github.com/errata-ai/vale

https://chrischinchilla.com/

 

Picks

Chris Ward:


On Writing by Stephen King

Write the Docs Society

https://git-fork.com/



Richard Littauer:


Bird by Bird by Anne Lamott

Web3 Summit 2019

https://stevenpressfield.com/books/the-war-of-art/

Special Guest: Chris Ward.