WriteTheDocs 2017 – Telling a great story on GitHub
Speaker Lauri Apple (Zalando), Open Source ambassador
Storytelling
Storytelling is important! That's how we understand the world, and telling stories (structuring information) communicates our ideas.
Ask "why", when publishing and releasing? Is this kind, is it fun, is it sustainable, does it tell a good story? We avoid these questions because we are stressed. Business and rushing things is a status symbol: it feels like lots of adrenalin, like heroism, and makes us feel important, but in truth it makes us burn out, and reduces our intelligence.
"'Everyone is too budy' is a cultural symptom of a lack of clear strategy and prioritization."
As a result, we lose the audience because we do not tell clear stories. This results from a lack of resources, wonky priorities, a too narrow focus on the project, and making things either too simple (just ship it) or too complex (within the narrow focus), and a lack of empathy with the audience.
We can … ask for feedback, create clear documentation. Clear documentation answers the Why?.
When you use an open source project with lacking documentation, consider contributing to the documentation.
This project gives you the opportunity to submit your documentation for review.
GitHub junkyards
Read Daniel H Pink "Drive" to understand the advantages of autonomy, and why Zalando now encourages autonomous team, code sharing, and open source work. Strategy shifts like this can result in GitHub junkyards: just releasing everything leads to >100 unstructured repositories without any narrative, purpose, audience, or expectations.
We love to publish, but we hate to edit. We believe that when something is released on GitHub, it is done, and that the code is enough, and everything is just marketing and bells and whistles. This is quantity-centered as well as self-centered, and also a lack of time management.
Junkyards are not planned, they just happen. Here, writers are a dev's best friend in helping to structure unstructured documentation, find the hidden narrative …
Bring sanity to your GitHub story
Go through your repositories to find the buried treasures. Apply basic storytelling. Center on storytelling, and quality over quantity.
Follow some sort guidelines on how to Open Source things, see for example the Zalando ones, which recommend one GitHub organization for the strongest projects, one GitHub organization for unfinished/WIP/dead projects, and one other organization for internal/private projects.
Use templates as the ones included in the Zalando repository.
Do market research – understand where and why your project exists within its ecosystem. Publish this information in a comparison table. And ask: Is this usable? Would you use this? Who are the users? (Create personas here). And then … put it in your README as well.
Teaching these skills takes time. Guidelines, templates, and more GitHub orgs are quick, but mindset and culture shifts towards storytelling take time.
Documentation is empowering
- Documentation creates consistency.
- Docs clarify processes.
- Docs create structure, both in the project, and in/between teams.
Think of it as README-Driven Development.
Wrapup
This is a process, and you should start it now. It will make your project better. Tell a story. And read the docs.