We talk to Diana Logan, Manager, Technical Writing at GitLab, about Gitlab’s approach to documentation and code.
- Working in an “Docs as Code” environment
- The upcoming GitLab Docs Hackathon
- Working for a fully remote, asynchronous organisation
- GitLab Docs Hackathon 23 – 27 January, 2023
- Five fast facts about docs as code at GitLab
- How to update GitLab documentation
This is the Cherryleaf Podcast.
So we normally start the interviews on the podcast by just asking people to say who they are and and what they do.
So yeah, I’m Diana Logan. I’m one of the technical writing managers at GitLab. Technical writer managers at GitLab are there to basically support the technical writing team and they work on getting our product documentation. So that’s the role and that’s everything from helping with prioritisation to career development and everything in between.
I thought this would be an interesting interview because GitLab has an unusual approach that you’re doing to documentation. It is unusual, so that I’d be interested in finding out about. But probably the starting point is for those that aren’t familiar with GitLab, as a company, it might be good to explain what it does.
Yeah yeah, sure. GitLab is basically a platform that helps people collaborate and develop software faster. It started back in 2011 as an open-source project and became a company in in 2014. I think we’re now at about 1800 team members in 60+ countries. And one of the quite unique things about how we work as a company is that it’s all remote and it has been since, you know, since inception. So for the technical writing team. For example, that means, I mean, I’m, I’m in the UK. My peer manager is is in South Africa and my manager is in the US. And the team of technical writers are completely globally distributed in APAC and Europe and in the States as well.
So one of the things that you’ve been doing is publishing some videos to YouTube and writing some blog posts. And publishing on the Git Lab website about the documentation team.
Another early question to ask is, overall, what’s GitLab’s approach to how it produces documentation? And specifically, working in the docs-as-code environment?
I think the blog post that you’re talking about. We talk quite a bit about how we use docs-as-code practices and for us really, the core component is collaboration. And so we work with developers. We work with Community members, product designers, product managers to develop our documentation and to maintain it.
We do that all in the same platform, so we do that all using GitLab and I mean docs-as-code is a fairly common approach in the industry now. It’s really aligning common developer tooling and practices with how you do docs. So for us that means it’s fairly typical.
And a team is working on a new feature for the next release. The docs changes can be in the same merge request as the code itself. So that means in one place you can see what the change is to the feature or what the new feature is.
You can also see you know where that might impact the UI text in the code. And technical writers that GitLab also work with product designers on UI text. And you can also see what the initial draft of documentation looks like for that feature.
The technical writer is ultimately responsible for reviewing the documentation part. But they can do that in this environment where they’ve got access to all these different subject matter experts who’ve worked on that feature in the same place, and they can do that asynchronously as well.
So that’s a key part of the remote side of the way GitLab works. That we do as much as possible publicly, and we do as much as possible in issues and merge requests, by “@” mentioning the person who he thinks got the answer. And ask your question and suggest changes on the code or on the documentation that goes with the code.
You mentioned the public aspect of GitLab. You can see how GitLab onboards new staff. You can see the HR policies. It’s quite interesting to see how open the organisation is to the world when there are still organisations which seem to have an issue with letting their staff access the Internet.
So from a practical perspective. We’ve got some clients that work in that way. Is it like this: that you would create a request to merge content in. You would work locally with the text editor to write the help content. And then push that up to GitLab. And then all the reviewing and editing is done in that environment. Is that roughly how it works?
That’s a workflow. It can. So for feature documentation it’s usually the developer who will write the first draft. OK. Or the feature lead who will write the first draft. So when the technical writer comes along, there’s often a a merge request already there.
Depending on the size of the docs change. If it’s relatively small, then it may be you just do that all in GitLab and just comment on the diff. Or make a suggestion on the diff. And then the developer can review it and accept it and apply the change.
If it’s bigger then, yes, you would typically pull the branch locally and look at it in whatever the editor of your choice. Be that Visual Studio Code editor or Sublime, or whatever editor is that you’re working on. And then go through the workflow that that you described.
So it depends on the size of the change.
So if you’ve got the developers writing the first draft, does that help in terms of getting reviews? Because one of the banes of being a technical author is writing some content and then it falling into a black hole of not being reviewed by a subject matter expert.
Just flipping it the other way around and having the developer work first, does that have an impact? Improve the processes of reviewing and approving and editing, or is it still the same challenges?
Definitely has an impact. And some of that comes from the way GitLab operates overall, so you know we have a public-facing handbook as you mentioned. A lot of our policies are public, so that idea of everybody is involved in documentation is really core to the way GitLab works.
So it’s not unusual for anyone in the organisation being a developer or a product manager or a salesperson to, if you see something that can be improved or inaccurate, or has perhaps become out of date. It, you don’t have to wait to go and find somebody to go and do that with specialised skills, you are empowered to open a merge request to make that change in the in the handbook or in the docs or in the product itself. Because that’s so fundamental to the way GitLab operates.
It naturally follows through anyway to the way that docs are produced. But it certainly helps us from an efficiency point of view. We’ve got the subject matter expert who is essentially creating the first draft. And we come in as a rep. You as technical writers, we may be aware of other experts that we can bring in to get a second pair of eyes on something.
And you know we’re empowered to do that as well, but that can all happen within the merge request or an issue. I can get help from someone in Australia. It doesn’t matter where they are. And while we all work different hours, you know you’re going to hopefully resolve it pretty much within the next 24 hours and then and move forward with that docs change or code change.
So when it’s who decides what content gets written, it’s everyone decide. And it’s. And they just do it and then it goes into the specialists to get it reviewed and improved.
Yeah. I mean we use as much automation as we can to keep the quality of easily preventable inconsistencies out. So we use Vale with rules that we develop and maintain to suit. GitLab always with a capital G and a capital L in the middle. And catch those types of easy things to automate.
And so we try and leverage as much of that side as possible. And then we have linters that run in the pipelines. As soon as you make a change and run a pipeline then it will go through those checks again. So that by the time I review it as a technical writer I can focus on is this addressing the most likely questions that it is going to have. Is it structured in a way that keeps task and concept information separate? You know all the usual things that that we go through to try and make it as readable and scannable as possible on a page.
So there’s new content being created and updated every week, every month, every day.
I think our pipeline at the moment is hourly. I need to check that. From when I approve a merge request, you will likely see it on the website a few hours later if everything goes through successfully. The changes are being merged all the time. I haven’t approved any this morning yet, but I’ve got a number of merge requests in my queue to review, or the ones that go through the changes will be on the website later on this afternoon.
We make heavy use of bots and bot technology and assignment, so if a merge request includes a page that is associated with a particular group, it can automatically add labels. And then potentially, we ping that writer to say, hey, this is coming through and make them aware that there’s a change there.
When it comes to contributing, can people from outside of GitLab contribute as well?
Yes they do. and in fact I was just looking before we started chatting.
GitLab releases on the 22nd of of every month has done since the beginning. So we always know that on the 22nd is when a new release comes out the features and merge requests and changes that all go into that particular release.
They come from the community and they come from themselves. And we also have this very rather lovely concept of every release an MVP, most valuable person, is nominated from the community. In recognition of what they have contributed to this particular release.
And it’s often, in fact the last three releases was just looking, it’s often the community contributor who’s done a significant amount of work on the documentation, either the content or the tooling.
We’re a fairly small team. There’s lots of things we’d love to do and that would help us work better, but we don’t have the time to do all of them, but we have this amazing community out there of folks who have the skills and wish to support what we do as well.
That was one example of someone who helped with tooling and then the previous release. We had a community contributor who made a significant amount of changes just to the content. So they ran Vale rules and found out where they were not compliant. And then just went in and fixed a lot of those sort of minor sort of irritating changes.
But again, it takes time to go through and do that. And that was someone who was, you know, keen to learn, keen to improve their docs-as-code skills. And took it as an opportunity to do that. So community is incredibly valuable to us, and it ultimately makes the docs and the product better.
Because one of the challenges. There’s a lot a number of people that want to become technical authors, technical writers, but they don’t have the experience. And there’s often that challenge of how do you get experience? And yeah, there can be events, but they can only run once a year. So the timing of that may not fit with what you’re doing. I I guess this may be an opportunity for or certainly something people should look at. As a way of building up some experience or dipping a toe into technical writing and getting more familiar with it.
Yeah, absolutely. We encourage folks who are either at the early stages of their technical writing career or they’ve been a technical writer for a while, but they haven’t done that much in docs-as-code, contributing to the docs at GitLab is a great way to get experience as a technical writer.
You’ve got a hackathon coming up, though, haven’t you?
We have, yeah. If I can do a shameless plug. We have a docs hackathon coming up. It’s we’re running it for a full week 23rd to the 27th of Jan. Obviously it’s completely remote. It’s asynchronous to sign up. If folks are interested, the website is www.about.gitlab.com/communities/hackathon.
And there’s a MeetUp link from that page. We do ask folks to register. We run a couple of kind of office hours type events at the beginning of the hackathon. To introduce them to the process and some of the ground rules. And tell them what they need to do to win swag and all that good stuff. So it’s like a regular GitLab hackathon, but we’ve decided to focus this one on docs, yeah.
And if you sign up and you’ll get all the instructions, but if you’re not able to make that hackathon, I just want to emphasise that you can contribute any time to GitLab docs.
There are instructions in the docs and how to do that. It doesn’t matter if you’ve never worked with Git before, there are very easy ways just to go through the web interface to make changes.
You don’t have to do things on the command line if you’re not comfortable yet, but we’d encourage you to also have a go at that. The technical writing team at GitLab is there if you open a merge request to change the docs. There’s then instructions. When you’re ready to get a review from the docs team, we will help you through the process if it’s not clear or if it goes a bit wrong somewhere along the way. That’s all part of the learning experience.
If somebody wanted to contribute, do they need a Linux machine, or they can do it on Windows and then and a text editor?
If they want to work locally, then having a text editor set up and so on is great. The instructions are on docs.gitlab.com. And then it’s how to update GitLab documentation, if you search for that, hopefully you’ll land on that page.
We’ve got issues that you can work on. Or you can just, if you find something in the docs that doesn’t look right and you’d like to suggest change, then you can just go to the bottom of the page and click “Edit this page”. And then and open it through the browser. So that that’s a very easy way to do it.
But you can also install tools locally and do a sort of more comprehensive local setup. If you want to learn more about the full docs-as-code workflow. Docs-as-code is partly about the tooling, but it’s really also about experiencing the collaboration with other people on a change.
Two questions sprung to mind there. In terms of the hackathon, how much time commitment would somebody expect to commit to?
As much or as little as they want. So we’ll have quite a lot of issues that we will open up just before the hackathon that folks, that sort of pre-prepared issues, that folks can work on. You can pick up one and see how that goes.
If you enjoy the process and you get through it really quickly, then you can pick up another one. And all we ask, and this is all explained in the ground rules, is that if an issue, a hackathon issue, is already assigned to someone else, that you don’t jump on that one. That pick one pick another one.
And does this approach do away with the need for Zoom meetings, face-to-face meetings? Does everybody work the system using GitLab or do you still have meetings? How do you?
For the hackathon, or just as a team.
No, we still meet. We try and work asynchronous first, but we do still have team meetings.
But they are, they are always agenda-ed. And they’re always recorded as well. If you can’t make the meeting. If that doesn’t work for how your day is structured, or you’ve got something else on, then that’s totally fine. You catch up on the recording, and you can also ask your own questions in the agenda and have somebody else voice them for you, if you’re not able to make it.
So, we do still meet. we make space to sort of deliberately have social time. You know, equivalent of water cooler time, with completely unagenda-ed meetings to just chat and laugh and let off some steam.
We have a concept of coffee chats and doughnut chats. We can randomly get assigned to anyone else in the company to chat. Coffee chats, which are typically an informal talk about absolutely anything you like. No agenda, just to have a bit of connection with someone else. And we do also meet up in person when it’s safe to do so, which it has been thankfully more often recently.
So we had the opportunity last quarter to have a series of meetups, which a lot of folks took advantage of, which was. I went surfing in Croyde with the GitLab team members who I’d never met before and actually don’t normally work with. Devon.
Where’s Croyde? Devon. Oh OK.
No, no. We also make space for meeting up face to face as well when we can.
Well you must be good surfer.
No, I’m not beginner, absolute beginner. Most of us were, I think, and it was a very choppy day, but I guess that’s good for surfing. Anyway, it was. It was good fun, not too cold either.
We’ve known each other, over the course of probably 10-15 years. Like lots of people, a career path can involve working at different organisations. What’s made GitLab different from some of the other organisations that you’ve worked for?
It’s all remote from the ground up. It always has been. So that means you know a lot of the processes which you know a lot of organisations have brought in during the pandemic has already been there. And that what we talked about earlier. That kind of documentation-first approach. And the entire company being very engaged in. Documenting things is fundamental to that.
It’s a great place to work. I love it. I think the other thing that I’ve experienced because I’ve worked remote before is a lot of people have worked remote before, but not necessarily in an asynchronous way. So having those asynchronous work practises trying to resolve things in issues going back and forth where everything is written down. And it doesn’t rely on somebody being in the same time zone or on a synchronous call to move forward. And find ways to bring the right people in and get past problems or sticking points has been a real eye opener and makes it a great place to work.
It gives me personally a lot of freedom to structure my day. Yeah, in a way that that works for me and my family and the things that I like doing in my spare time as well. So that’s from a quality of life point of view. It’s quite transformational.
We get quite a few people that wanting they haven’t heard of technical authoring as a career. They want to become a technical author, And then there’s this issue of how do you start without experience, for the experience? That perfect chicken and egg situation. Because although training and certification is important, can add value, you do need experience to become a decent technical author. And most organisations want to hire somebody that’s got some basic experience doing stuff. So the challenge for them is finding those opportunities to get involved and start contributing where they are, so they can build up some basic skills. Again, technical documentation, developer orientated documentation can scare the pants off people. And docs-as-code can as well, when in many ways it’s still the fundamentals. With the developer audience, often the questions are what does this thing do? Why should I use it? How do I use it?
So it’s good to find out and learn about these opportunities. These routes in that people can take advantage of, to get into this space.
Yeah, absolutely. I mean we have folks on the technical writing team who started as community contributors and then joined the team permanently. So it’s, when we go through the interview process with folks, we always encourage them to. They feel like they need to learn more about docs-as-code or more about DevOps and come and contribute to the docs. That’s an easy way to start building out your portfolio.
And because it’s all in the public domain, then it’s very easy to create a portfolio and then point people to merge requests where they’ve helped improve a particular section of document. And you can show the before and after in the diff very nicely. And it’s a great way to build up a portfolio.
I’ll add these to the show notes, but could you remind us of the important links if people want to explore this further?
Yes. First of all, the hackathon one, which is you can just do a search for “GitLab Hackathon”. This page should come up, it’s about.gitlab.com/community/hackathon. And then for just general instructions, for getting started with contributing to the docs, you can go to docs.gitlab.com and scroll to the bottom of any main page. So to navigate to a regular page, it’ll say edit, “Edit this page”, so click on that. That’s one way to start.
If you want fuller instructions for how to contribute, then it’s docs.gitlab.com/ee/development/documentation/workflow. It’s a bit of a long URL, but if you search for “Contributing to GitLab documentation” that should bring you to the same place. And I’ll give you those links for as well.
Thank you. There’s the YouTube videos and the introduction to using GitLab as a technical writing team.
Yes, so the GitLab Unfiltered YouTube channel. There’s a ton of videos on there. But yeah, and I think the blog links to it as well, which is “Five fast facts about docs-as-code at GitLab” and then at the bottom of that blog post, there’s a link to that video.
What you’re talking about, that was really interesting. So I think that’s all the questions I’ve got for the moment. It was good chatting to you again and thank you very much.
Yeah, thank you Ellis, it’s been a pleasure to be on.