##  [Version the Docs - Version control &amp; documentation](/version-docs-version-control-documentation) 

 ```
  <div class="field-collection-container clearfix"><div class="field field-name-field-hero-content"><div class="field-collection-view clearfix view-mode-full field-collection-view-final">
```

# VERSION CONTROL &amp; DOCUMENTATION 

Speakers from leading GIT code repositories, talking about how their teams dogfood their own tools to do their documentation - Recordings, slides and summaries of presentations at the Write The Docs' London meetup on January 24, 2017

 

 

 

 









 







### Design thinking at Bitbucket: building a developer experience from scratch

### **[Becky Todd](https://twitter.com/beckatodd)**

#### 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 &amp; 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](https://developer.atlassian.com/blog/2016/11/announcing-dac-beta/#technical-highlights) 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.

**[Q&amp;A:](https://youtu.be/5ez9fM-amVA?t=16m42s)**

- 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.



 

#### Becky's **[presentation slides](http://www.slideshare.net/BeckyTodd3/design-thinking-building-a-developer-experience-from-scratch)**

   **[Design thinking: Building a developer experience from scratch](//www.slideshare.net/BeckyTodd3/design-thinking-building-a-developer-experience-from-scratch "Design thinking: Building a developer experience from scratch")**  from **[Becky Todd](//www.slideshare.net/BeckyTodd3)** 

#### and the **[video recording](https://youtu.be/5ez9fM-amVA)**



  



 









 

 









 







 

 

 





### 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&amp;A:](https://youtu.be/0-W0M0XG5dw?t=25m39s)**  
\* 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](https://twitter.com/teoli2003)**, AirMozilla (Creative Commons Attribution Share-Alike License v3.0).



 

 





 

 

 



We are working on an open source documentation portal that implements a workflow similar to the above. Want to stay informed? Sign up to our developer portal mailing list.

 









 

 Subscribe 

 

 









*We will not publish, share, or sell your email address in any way.