GitLab UX Team, 23 Sep 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Introduction to using GitLab as a technical writing team

Description

This video shows you how GitLab helps the Technical Writing team deliver the product documentation.

GitLab and the world of DevOps can be a bit daunting, particularly if you are not a software developer or seasoned DevOps professional. By looking at GitLab through the lens of a team that is in an adjacent and supporting role to software development, it will hopefully help make some of the workflows and capabilities a bit more relatable.

It's for:
- GitLab team and community members at who want to understand, at a high level, what the Technical Writing team does.
- Technical Writing candidates considering applying for a Technical Writer role at GitLab.
- Folks in the wider industry who want to find out more about docs-as-code.

https://about.gitlab.com/handbook/product/ux/technical-writing/
https://docs.gitlab.com/ee/development/documentation/index.html#contributing-to-docs

A

I’M diana logan,, one of the technical writing managers here at gitlab.

A

In this short, video, I’m going to show you how gitlab the product.

A

Helps the technical writing team deliver the product documentation for gitlab.

A

One of the reasons I thought this would be helpful to dig into, is because gitlab and the world of devops can be a bit daunting.

A

If you are not a software developer or seasoned devops, professional.

A

But by looking at gitlab through the lens of a team that is in an adjacent and supporting role to software development,.

A

It will hopefully help make some of the workflows and capabilities a bit more relatable.

A

At gitlab, technical writers, work with developers, product managers, and the community.

A

To develop and deliver the product documentation you find on docs.gitlab.com.

A

They also work closely with product designers.

A

On the words that appear in the user interface error, messages,, tooltips, labels and so on.

A

Good documentation meets the evolving needs of all gitlab customers,, users, and administrators.

A

It educates readers and enables them to efficiently configure, use,.

A

And troubleshoot gitlab.

A

so,: how do we do this with a constantly evolving product,? Keep the quality up,.

A

And deliver value at speed?.

A

The answer comes in two parts..

A

The first part is that we embrace docs as code practices.

A

This means treating documentation development in the same way as code. Development.-.

A

Sharing tools to maximise collaboration,.

A

A high level of automation, and a trusted set of reviewers., so what? docs as code workflows, are actually used by many tech companies. Today.

A

What’S different about the technical writing at gitlab is that we are able to carry out most of our work in that single platform gitlab as writers and reviewers. We’Re not constantly switching between one app to edit, another app to figure out why the site isn't building,.

A

And another app to track the work.

A

The gitlab devops stages highlight some of the key features.

A

We use in the technical writing workflow when we are planning, writing and reviewing,, and deploying and publishing the documentation.

A

Let’S take a closer look at how this works in practice.

A

Starting with planning:, how do we know what’s coming up in the next release, and how much support the development teams are expecting from us as technical writers?.

A

So each development team, similar to an agile scrum team.

A

Along with their product, manager, designer, and technical writer,.

A

Will review the planned work for the upcoming release.

A

They use issue boards where documentation effort has been identified.

A

The teams, collaborate asynchronously using planning issues.

A

Like this one for the pipeline authoring, team.

A

As a technical writing team,, we then roll up the planning effort.

A

From forty plus individual development teams and look at our coverage in a single planning issue for the next milestone., we use this view to help each other get up to speed. If we need to provide coverage.

A

While team members are taking time off, to support each other, if one group is more heavily loaded than another.

A

Alright, moving on from planning to the writing and reviewing.

A

So the source for the product documentation is kept in repositories in gitlab.

A

And when a developer makes a set of code changes that will, for example,.

A

Deliver a new feature in the next release, hey’ll make the first draft change to the affected documentation, files,.

A

Often, in the same, merge request as the code change.

A

At the same time, pipelines are running automated tests and scans to check. The changes can be merged.

A

This will include documentation, linting, which checks on terminology and spelling, and valid markdown.

A

The technical writer reviews and suggests changes.

A

the developer discusses, clarifies and applies the changes,.

A

And from a technical writing perspective,, the merge request is ready to go.

A

Next, we want to get the changes into the hands of users as soon as we can.

A

This moves us into the deploying and publishing.

A

So when the merge request is approved and merged,, the pipeline will run again with the same checks and tests as before.

A

And the changes will be published on the docs site shortly. After.

A

To recap, it’s, not just docs as code practices, that we use, it’s docs as code using gitlab as the single platform that we work in along with designers, developers, product managers,.

A

And community members to build and maintain the product documentation.

A

Gitlab supports the technical writing team throughout their workflow.

A

When planning technical writing work for an upcoming release,.

A

Issues and issue boards play a key role in asynchronous discussions, and progress. Tracking.

A

When writing and reviewing documentation, working in repositories all held in gitlab, allow code and docs changes to be kept in synch.

A

Continuous integration pipelines alert the team early to any issues such as non-standard markdown,.

A

That may cause problems when we want to deploy the changes to production.

A

Finally,, when the changes are merged, continuous delivery, using gitlab pages.

A

Automatically deploys the changes to a static site.

A

That serves the updated content to users.

A

So, I asked axil and suzanne,.

A

Senior and staff writers at gitlab, what they liked about using the product.

A

and axil said the thing I like most about using gitlab to work on technical documentation.

A

Is the tools it provides to collaborate with my peers.

A

From issues to merge, requests, and testing to deployments, they're, all under the same roof.

A

Suzanne said: “being, able to do all of my work in one place, is great.

A

There's a historical record of everything. I've done at work, --no need to search multiple locations for something I did a year. Ago.

A

We are incredibly proud of the work we do to support our engineering teams,.

A

Customers, and contributors be successful with gitlab.

A

We are a work in progress and we continue to iterate.

A

We’D love you to be part of making the docs even better at gitlab.

A

I hope this talk has helped give you some new perspectives on how different types of teams,.

A

Such as our technical writing, team, can be successful with gitlab.

A

Thanks for listening.