VERSION CONTROL & DOCUMENTATION
Design thinking at Bitbucket: building a developer experience from scratch
Becky Todd
Senior Technical Writer on the Developer Relations Team at Atlassian
They redesigned content and workflow because they needed:
- the current version of everything
- easy search & navigation
- an improvement to their content creation process
Challenges:
- repo management: what structure to use?
- many contributors - how to put it to 1 place?
- how to help contributors use git? onboarding issues vs community contributions
- how to keep it searchable and up-to-date? large files?
So far
- Integrated auto-generated content with handcrafted content so they are displayed together on the static site.
- On the live developer site an "improve this page" button takes you to the in-the-UI-editor in Bitbucket. Content written in github flavoured markdown. The git forking work is done for contributors in the background.
- Tools in detail on Atlassian's developer blog.
Highly recommended
- User testing brought up unexpected new learnings.
- Content champions support: personal presence for coaching, mentoring on what people could and couldn't do with the content and on git.
- Changed from one repo to multiple.
- Confluence.
- Review cycle: a new branch deployed on a staging server, 2 people need to verify each merge. Teams decide themselves on who writes what. 1 writes, 1 reviews to grammar and style standards and 1 tests if it's working.
- Review etiquette: unless full direct edit is requested, suggest in comments.
Version The Docs at GitLab
Using different repos because their docs always load within the main project, in an editable docs folder.
They used to rebuild the docs every 30 mins - now they have triggers that initiate automatic rebuild of the docs every time there’s a change.
Anybody has to be able to contribute to the docs. They can get their exact setup for this. Everything is in the UI: edit in place, ask for merge request - much easier for non-technical persons, although it could be made even more simple.
They now rely on the writers to use the correct spelling and grammar checker they can work into their editor - but they need a consistent way to do it without each writer’s setup. Planning to include spell check into their linters.
Every process goes into the handbook, almost everything is open.
Challenge: how to support all versions of the docs? The gitlab versions locally installed have their own docs with them. In beta now: hosting all versions’ documentation on gitlab docs and having them searchable - without confusing the users. Still to solve version-tagging towards search engines.
Q&A:
* structure: not nest things too deep
* keep single topics
* suggestion: show context to help users’ orientation
* tutorials and guides: flatten as much as possible to the base topic and simplify. Put the existing software hierarchy into a TOC and then try to flatten.
Original recording of the meetup by Jean-Yves Perrier, AirMozilla (Creative Commons Attribution Share-Alike License v3.0).
