Dan Allen, the lead moderator, welcomed everyone and encouraged everyone to participate We’re here to talk about writing, primarily technical documentation but beyond that too. Team organisation Technical challenges
Introductions. A broad cross-section of roles, interests, and tools:
-
Developers
-
IT architects
-
Writers
-
Consultants
-
JIRA, Confluence, Wiki, Asciidoctor
-
Making documentation as useful as possible
-
How do you document with an agile approach when the deliverable is running software?
-
Dealing with people who hate to write documentation
-
Living documentation
-
Structuring and segmenting documentation for new comers and experienced users
-
Documenting different concepts for users with different levels of experience and technical knowledge
Dan is excited to hear that everyone is keen to improve documentation rather than running away from it.
Think about your code. Do you have projects with no technical team lead? Why would you have documentation with no content owner? Break the documentation up and assign ownership? Consistency of message, should the product description come from marketing or from a single central source? Spring’s getting started guides are a good example of sharing common content.
Twillio: someone owns the documentation. Getting started guides, tutorials, example code. Anyone at Twillio can write and update documentaiton. Technical writers are developers. Everyone on the tech writing team used to be a developer.
Solutions documented in Word by architects. Making it easy to write docs has led to developers writing documentation. Asciidoctor has helped to empower people. People want to write if it’s easy. It’s better if the people who know how stuff works document it.
Differentation between API docs and getting started guides and tutorials. Developers want to write API docs, but not getting started guides and tutorials.
Benefits of mixing hand written and generated documentation. Technical accuracy and easy to consume prose. Twillio has prose in its docs. You’re not looking for /messages, you’re looking to learn how to list all the messages.
Some have the talent to write something clear and concise. Quality varies as a result. Documentation is for other internal developers. Review is lacking. It’s easier to ask someone than to look something up in the documentation. People will wait if someone’s not available, rather than read the docs. People are expected to write good code, but not to write good documentation.
Twillio education team review documentation between each other to ensure its quality.
Sometimes it’s hard to know where the documentation is. Partial documentation is dangerous as people stop looking.
Agile process for documentation. Use the same process for developing documentation as for developing code. Agile board, issues, everything goes through the same process. Product owner reads the documentation to learn how to use what’s been delivered in the sprint. If it’s not documented, it hasn’t been delivered. Documentation becomes part of the acceptance tests.
What you can express in code should be expressed in code, but what you can’t needs to be documented. And it needs to be a simple as possible. With the tooling that’s around, there’s more and more that you can commit that describes things. BDD fixtures are a form of documentation. The line between code and documentation starts to blur. Concept, purpose can’t be documented in code.
Serenity. Cucumber feature files. Feature may be too technical and can’t be shown to product owners. There’s a gap that needs to be bridged. Requires some transformation as things may be too low-level or not in the right format. Creating good feature files is very time consuming and that time isn’t available. It gets neglected and people spend time on coding instead.
Manage everything in Git. Challenge for less technical people. Dan belieces that documentation problem can be solved with… more documentation. Explaining to someone by thinking out load can be counter-productive. Carefully documenting first can be much more successful. Easy to assume that using GitHub is easy. Pull request concept is alien to people who aren’t familiar with it. Metaphors can help. Branches are pieces of paper. New piece of paper, new branch. Domain specialists are technical (finance, for example) but not familiar with GitHub. They still use "version control" but not as we know it. Buiding a connection between what they do to a new way can make adoption much easier.
Ownership shouldn’t be who’s writing the documentation. Other people who may want to contribute should be empowered to do so. Sharepoint has something that helps a little, but people aren’t happy with it. Grails, improve you doc button. Nice step, but it’s not quite there as you still need an account, and to understand Git. GitHub’s wiki hides a lot of the Git machinery. Still room for improvement to lower the barrier for people who want to improve documentation.
Should we view documentation sites as software itself. Do we need documentation engineers to manage the ever increasing stack of documentaiton?
How do you find a content owner? Documentation may be an integration of all teams in a company. In some ways it touches everyone. Someone has to pull it all together. Is it a layer above that keeps everyone communicating rather than a silo? Good documentation can allow a company to excel. Being engineer-driven can help.
How do you know if your documentation site is down? Wait for someone on Twitter to yell.
Time to production can be motivating for improving documentation, but it can still be hard to get people to use the documentation.