Skip to content
Snippets Groups Projects
Commit 4ce6c9fb authored by Cynthia "Arty" Ng's avatar Cynthia "Arty" Ng :speech_balloon:
Browse files

Add ReferenceLinks rule and fix errors

parent 148dedba
No related branches found
No related tags found
1 merge request!6682Add ReferenceLinks rule and fix errors
Showing
with 79 additions and 91 deletions
---
# Error: handbook.ReferenceLinks
#
# Checks for reference-style links that should be converted to inline links.
#
# For a list of all options, see https://vale.sh/docs/topics/styles/
extends: existence
message: "Put this link inline with the rest of the text."
link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links
level: error
scope: raw
raw:
- '\n\[[^\^\]]*\]: .*'
The groups in the [Create stage][stage] conduct asynchronous standups in the
[#g_create_standup] channel 3 times a week, on Monday, Wednesday, and Friday.
The groups in the [Create stage](/handbook/product/categories/#create-stage) conduct asynchronous standups in the
[#g_create_standup](https://gitlab.slack.com/archives/g_create_standup) channel 3 times a week, on Monday, Wednesday, and Friday.
The goal is to support the members of these groups in connecting at a personal level,
not to check in on people's progress or replace any existing processes to communicate
......@@ -9,10 +9,5 @@ status or ask for help, and the questions are written with that in mind:
1. What are you planning to do today?
1. Is anything blocking your progress or productivity?
For more background, see the [Async standup feedback issue] on the
[Create stage issue tracker].
[stage]: /handbook/product/categories/#create-stage
[#g_create_standup]: https://gitlab.slack.com/archives/g_create_standup
[Async standup feedback issue]: https://gitlab.com/gitlab-org/create-stage/issues/4
[Create stage issue tracker]: https://gitlab.com/gitlab-org/create-stage/issues
For more background, see the [Async standup feedback issue](https://gitlab.com/gitlab-org/create-stage/issues/4) on the
[Create stage issue tracker](https://gitlab.com/gitlab-org/create-stage/issues).
The groups in the [Create stage][stage] organize regular [Deep Dive sessions]
The groups in the [Create stage](/handbook/product/categories/#create-stage) organize regular [Deep Dive sessions](/handbook/communication/deep-dives/)
to share our domain specific knowledge with others in the stage, the organization,
and the wider community. All existing Deep Dives can be found on [GitLab Unfiltered][Youtube]
and the wider community. All existing Deep Dives can be found on [GitLab Unfiltered](https://www.youtube.com/playlist?list=PL05JrBw4t0KqsiWzD0YZYp9xSxgTRoWxH)
with slides and recordings in the descriptions. For Create specific Deep Dives, there is a
[different playlist][Create playlist]. To find more information on upcoming sessions,
or to propose a new topic, please see the [epic][Deep Dive issue tracker].
[stage]: /handbook/product/categories/#create-stage
[Deep Dive sessions]: /handbook/communication/deep-dives/
[Deep Dive issue tracker]: https://gitlab.com/groups/gitlab-org/-/epics/2410
[Youtube]: https://www.youtube.com/playlist?list=PL05JrBw4t0KqsiWzD0YZYp9xSxgTRoWxH
[Create playlist]: https://www.youtube.com/playlist?list=PLFGfElNsQthYqXzKeq9l-ujLiChPAZag4
[different playlist](https://www.youtube.com/playlist?list=PLFGfElNsQthYqXzKeq9l-ujLiChPAZag4). To find more information on upcoming sessions,
or to propose a new topic, please see the [epic](https://gitlab.com/groups/gitlab-org/-/epics/2410).
We use a lightweight system of issue weighting to help with capacity planning,
with the knowledge that [things take longer than you think]. These weights are
with the knowledge that [things take longer than you think](https://erikbern.com/2019/04/15/why-software-projects-take-longer-than-you-think-a-statistical-model.html). These weights are
used for capacity planning and the main focus is on making sure the overall sum
of the weights is reasonable.
......@@ -22,5 +22,3 @@ Anything larger than 5 should be broken down if possible.
We look at recent releases and upcoming availability to determine the
weight available for a release.
[things take longer than you think]: https://erikbern.com/2019/04/15/why-software-projects-take-longer-than-you-think-a-statistical-model.html
We have a [metrics dashboard][dashboard] intended to
track against some of the [Development Department KPIs][kpis], particularly
We have a [metrics dashboard](https://app.periscopedata.com/app/gitlab/561630/Dev-Sub-department-Overview-Dashboard) intended to
track against some of the [Development Department KPIs](/handbook/company/kpis/#development-department-kpis), particularly
those around merge request creation and acceptance. From that dashboard, the
following charts shows [MR Rate].
following charts shows [MR Rate](/handbook/engineering/development/performance-indicators/#mr-rate).
{{% sisense dashboard="561630" chart="7415633" %}}
......@@ -9,7 +9,3 @@ The following chart shows the MR Rate of the Dev section as a whole, for the
identification of trends:
{{% sisense dashboard="561630" chart="7305986" %}}
[dashboard]: https://app.periscopedata.com/app/gitlab/561630/Dev-Sub-department-Overview-Dashboard
[kpis]: /company/kpis/#development-department-kpis
[MR Rate]: /handbook/engineering/development/performance-indicators/#mr-rate
Top 10 Reasons to Work for GitLab:
1. [Mission]({{< ref "mission" >}}): Everyone can contribute
1. [Results]({{< ref "values#results" >}}): [Fast growth](https://about.gitlab.com/why-gitlab), [ambitious vision](https://about.gitlab.com/direction/#vision)
1. [Results](/handbook/values/#results): [Fast growth](https://about.gitlab.com/why-gitlab), [ambitious vision](https://about.gitlab.com/direction/#vision)
1. [Flexible Work Hours](/handbook/company/culture/all-remote/people#those-who-value-flexibility-and-autonomy): Plan your day so you are there for other people & have time for personal interests
1. [Transparency]({{< ref "values#transparency" >}}): [Over 2,000 webpages in GitLab handbook]({{< ref "about#count-handbook-pages" >}}), [GitLab Unfiltered](https://www.youtube.com/gitlab-unfiltered) YouTube channel
1. [Iteration]({{< ref "values#iteration" >}}): [Empower people to be effective & have an impact]({{< ref "values#collaboration" >}}), [Merge Request rate](https://about.gitlab.com/handbook/engineering/metrics/#merge-request-rate), [We dogfood our own product]({{< ref "using-gitlab-at-gitlab#introverts-of-gitlab" >}}), [Directly responsible individuals]({{< ref "directly-responsible-individuals" >}})
1. [Diversity, Inclusion & Belonging]({{< ref "values#diversity-inclusion" >}}): [A focus on gender parity]({{< ref "people-success-performance-indicators#diversity---women-at-gitlab" >}}),
1. [Transparency](/handbook/values/#transparency): [Over 2,000 webpages in GitLab handbook]({{< ref "about#count-handbook-pages" >}}), [GitLab Unfiltered](https://www.youtube.com/gitlab-unfiltered) YouTube channel
1. [Iteration](/handbook/values/#iteration): [Empower people to be effective & have an impact](/handbook/values/#collaboration), [Merge Request rate](https://about.gitlab.com/handbook/engineering/metrics/#merge-request-rate), [We dogfood our own product]({{< ref "using-gitlab-at-gitlab#introverts-of-gitlab" >}}), [Directly responsible individuals]({{< ref "directly-responsible-individuals" >}})
1. [Diversity, Inclusion & Belonging](/handbook/values/#diversity-inclusion): [A focus on gender parity]({{< ref "people-success-performance-indicators#diversity---women-at-gitlab" >}}),
[Team Member Resource Groups]({{< ref "erg-guide#definition-of-the-tmg---team-member-groups" >}}), [other initiatives](/handbook/company/culture/inclusion#what-we-are-doing-with-diversity-inclusion--belonging)
1. [Collaboration]({{< ref "values#collaboration" >}}): [Kindness]({{< ref "values#kindness" >}}), [saying thanks]({{< ref "values#say-thanks" >}}), [intentionally organize informal communication](/handbook/company/culture/all-remote/informal-communication), [no ego]({{< ref "values#no-ego" >}})
1. [Collaboration](/handbook/values/#collaboration): [Kindness]({{< ref "values#kindness" >}}), [saying thanks]({{< ref "values#say-thanks" >}}), [intentionally organize informal communication](/handbook/company/culture/all-remote/informal-communication), [no ego]({{< ref "values#no-ego" >}})
1. [Total Rewards]({{< ref "compensation#gitlabs-compensation-principles" >}}): [Competitive market rates for compensation]({{< ref "compensation#competitive-rate" >}}), [Equity compensation](/handbook/total-rewards/stock-options/), [global benefits (inclusive of office equipment)](/handbook/finance/expenses/#-office-equipment-and-supplies)
1. [Work/Life Harmony](/handbook/company/culture/all-remote/people#worklife-harmony): [Flexible workday](/handbook/company/culture/all-remote/guide#non-linear-workday), [Family and Friends days]({{< ref "family-and-friends-day" >}})
1. [Remote Done Right]({{< ref "workplace" >}}): [One of the world's largest all-remote companies]({{< ref "workplace#all-remote-flywheel" >}}), [prolific inventor of remote best practices]({{< ref "workplace#vision" >}})
......@@ -64,7 +64,7 @@ Sid is easy to talk to on any subject. He is good at drawing people out and chal
1. Sid is worth managing up to. The learning curve he’s on is as steep as it gets, and he does learn/change/adapt readily, so you will see a return from investment.
1. Sid is GitLab's product visionary.
1. He’s the anchor of all-remote.
1. Sid is the source of our [transparency value]({{< ref "values#transparency" >}}).
1. Sid is the source of our [transparency value](/handbook/values/#transparency).
1. Sid is also the driving force for our iteration value. For example, he may hold [Iteration Office Hours](#iteration-office-hours).
1. Sid really values 1:1 preparation.
1. Sid believes in “strong opinions, weakly held.” He doesn’t always seem like it, but he will change his mind quickly if you present him with compelling new information and a data driven perspective.
......@@ -82,7 +82,7 @@ This section was started by GitLab's Head of Remote Darren M. to coach and provi
1. Make it personal. Ask Sid “*Why do you feel this way?*” or "*What did you learn from this?*" or “*What happens in your day that relates to this?*” Sid is able to craft stories which involve personal anecdotes that create deeper understanding and learning for the audience.
1. ***Be bold in your questions***. Sid enjoys the challenge of a hard or (thoughtfully) audacious question. Sid fields a lot of questions on a daily basis, many of which can be answered by [referencing the GitLab handbook](/handbook/company/culture/all-remote/self-service/#answer-with-a-link). By referencing a current state in the handbook and digging for more context and nuance, this provides opportunity for Sid to answer and provide value to more than just the interviewer — the new context should be added to the handbook after the interview to benefit all.
1. ***Apply to the [CEO Shadow](/handbook/ceo/shadow/) program***. There is no equivalent to watching Sid meet with and interview a global array of people for two weeks. The program is an efficient way to gain a deeper understanding of Sid's style and personality. Moreover, the program enables GitLab team members to realize that Sid is not only a CEO, but also an individual who enjoys working with others who will challenge him and accelerate his personal growth.
1. ***Don’t be ashamed with ending early***. It is natural to try to fill an allotted time block with a CEO. Remember GitLab's value of [Efficiency]({{< ref "values#efficiency" >}}) and be bold if you're able to progress through an agenda quickly. A recommend close-out statement is: “*We were very efficient driving through the agenda. Any final points before we close?*
1. ***Don’t be ashamed with ending early***. It is natural to try to fill an allotted time block with a CEO. Remember GitLab's value of [Efficiency](/handbook/values/#efficiency) and be bold if you're able to progress through an agenda quickly. A recommend close-out statement is: “*We were very efficient driving through the agenda. Any final points before we close?*
1. ***Listen to Sid's [interview](https://changelog.com/founderstalk/70) on the Changelog podcast***. There are hundreds of hours of Sid speaking on the internet, but this interview showcases a talented interviewer (Adam) extracting nuance and detail from Sid in a comfortable and professional way. The interviewer is thoughtful yet audacious in his questions, while also bold and considerate. He challenges Sid and commands mutual respect.
## Communication
......@@ -117,7 +117,7 @@ Sometimes I will ask to be kept apprised of an action item or follow up. One com
I get a lot of @ mentions in Slack, often when I'm being discussed. Please only @ mention me when you need me to see something or approve something, when you just want to refer to me you can just say Sid. This saves time and enables increased efficiency.
If there is a suggested message draft that you’d like me to post in Slack, you should send two messages to me. The first message should include the context behind the ask, the suggested timing for posting, and a link to the channel that the draft will be posted in. Under this message reply in thread with your second message. This should only contain the draft message. This allows me to easily copy and paste on mobile.
If there is a suggested message draft that you’d like me to post in Slack, you should send two messages to me. The first message should include the context behind the ask, the suggested timing for posting, and a link to the channel that the draft will be posted in. Under this message reply in thread with your second message. This should only contain the draft message. This allows me to easily copy and paste on mobile.
### No Sacred Cows
......@@ -400,7 +400,7 @@ An applicant asked how we manage to do this and these are the factors that come
1. Everyone in the business wants to do the right thing for the existing users and customers. The problem is that people already using you prefer stability in scope over change in scope. You need to optimize for all people, both the current users and people not using GitLab yet because it is missing features.
1. Separate execution from goal-setting. At GitLab, product decides what to ship and engineering is responsible for shipping it. Both report in to the CEO. If you have a head of product that also runs engineering, they are more likely to slow down because it will make engineers' tasks easier.
1. Separate decision making from giving input. [As detailed in our handbook](/handbook/leadership/#making-decisions) we leave the decision to the person doing the work or their manager, this prevents the need for exponentially more coordination as we grow.
1. We [iterate]({{< ref "values#iteration" >}}) so that we keep learning quickly and reduce the risk of decisions.
1. We [iterate](/handbook/values/#iteration) so that we keep learning quickly and reduce the risk of decisions.
1. We have [functional teams](/handbook/leadership/#no-matrix-organization) that make us efficient but as mentioned in that text we promote organic cross-functional collaboration by giving people stable natural counterparts.
## Evolution of the handbook
......
......@@ -319,7 +319,7 @@ The [Work-from-Home Field Guide](/handbook/company/culture/all-remote/work-from-
### Remote Work playlist on GitLab Unfiltered
GitLab is a very [transparent]({{< ref "values#transparency" >}}) company. As such, our AMAs, webinars, and other conversations with team members and other companies are uploaded to a dedicated [Remote Work playlist](https://www.youtube.com/playlist?list=PL05JrBw4t0Kq7QUX-Ux5fOunQotqJbECc) on the GitLab Unfiltered YouTube channel.
GitLab is a very [transparent](/handbook/values/#transparency) company. As such, our AMAs, webinars, and other conversations with team members and other companies are uploaded to a dedicated [Remote Work playlist](https://www.youtube.com/playlist?list=PL05JrBw4t0Kq7QUX-Ux5fOunQotqJbECc) on the GitLab Unfiltered YouTube channel.
### Universal Remote webcast playlist on GitLab YouTube channel
......@@ -410,7 +410,7 @@ The team's primary home for publishing informational guides and content is the [
### Video
GitLab is a very [transparent]({{< ref "values#transparency" >}}) company. As such, our remote-centric AMAs, webinars, and other conversations with team members and other companies are uploaded to a dedicated [Remote Work playlist](https://www.youtube.com/playlist?list=PL05JrBw4t0Kq7QUX-Ux5fOunQotqJbECc) on the GitLab Unfiltered YouTube channel.
GitLab is a very [transparent](/handbook/values/#transparency) company. As such, our remote-centric AMAs, webinars, and other conversations with team members and other companies are uploaded to a dedicated [Remote Work playlist](https://www.youtube.com/playlist?list=PL05JrBw4t0Kq7QUX-Ux5fOunQotqJbECc) on the GitLab Unfiltered YouTube channel.
### Events, panels, keynotes and webinars
......
......@@ -411,7 +411,7 @@ The CEO Shadows maintain a project called [CEO Shadow Tasks](https://gitlab.com/
Here are some examples:
1. Make [handbook]({{< ref handbook >}}) updates (use the [ceo-shadow](https://gitlab.com/gitlab-com/content-sites/handbook/-/merge_requests?scope=all&state=all&label_name[]=ceo-shadow) label).
Post the MR links in the `#ceo` Slack channel and `@`-reference the CEO so the CEO knows they have been completed. It is not required to create issues for these tasks. Go directly to a merge request if it is more [efficient]({{< ref "values#efficiency" >}}).
Post the MR links in the `#ceo` Slack channel and `@`-reference the CEO so the CEO knows they have been completed. It is not required to create issues for these tasks. Go directly to a merge request if it is more [efficient](/handbook/values/#efficiency).
1. [Draft a "tweet storm"](#drafting-a-tweet-storm).
1. Solve urgent issues. For example, help solve a complaint from a customer or coordinate the response to a technical issue.
1. Go through open merge requests and work towards merging or closing any that have [not been merged](https://gitlab.com/gitlab-com/content-sites/handbook/-/merge_requests?scope=all&state=opened&label_name[]=ceo-shadow).
......
......@@ -201,10 +201,10 @@ When referring to email that recipients should have received, reference the send
If something is behaving strangely on [https://gitlab.com](https://gitlab.com), it might be a bug. It could also mean that something was changed intentionally.
Please search if the issue has already [been reported][issue-list]. If it has not been reported, and you are sure it is a bug, please [file an issue](#issues).
Please search if the issue has already [been reported](https://gitlab.com/groups/gitlab-org/-/issues). If it has not been reported, and you are sure it is a bug, please [file an issue](#issues).
If you are unsure whether the behavior you experience is a bug, you may ask in the Slack channel [#is-this-known][is-this-known-slack].
If you know which stage of the DevOps lifecycle is affected, it is also okay to ask in #s\_{stage}, for example [#s_manage][s_manage-slack].
If you are unsure whether the behavior you experience is a bug, you may ask in the Slack channel [#is-this-known](https://gitlab.slack.com/messages/CETG54GQ0/).
If you know which stage of the DevOps lifecycle is affected, it is also okay to ask in #s\_{stage}, for example [#s_manage](https://gitlab.slack.com/messages/CBFCUM0RX).
When you ask:
......@@ -212,15 +212,7 @@ When you ask:
- Describe the behavior you are experiencing, this makes it searchable and easier to understand.
Different people might look for different things in the same screenshots.
- Asking in a single channel helps discoverability, duplicated efforts and reduces noise in other channels.
Please refrain from asking in general purpose channels like [#frontend][fe-slack], [#backend][be-slack], [#development][dev-slack] or [#questions][q-slack].
[issue-list]: https://gitlab.com/groups/gitlab-org/-/issues
[is-this-known-slack]: https://gitlab.slack.com/messages/CETG54GQ0/
[s_manage-slack]: https://gitlab.slack.com/messages/CBFCUM0RX
[fe-slack]: https://gitlab.slack.com/messages/C0GQHHPGW/
[be-slack]: https://gitlab.slack.com/messages/C8HG8D9MY/
[dev-slack]: https://gitlab.slack.com/messages/C02PF508L/
[q-slack]: https://gitlab.slack.com/messages/C0AR2KW4B/
Please refrain from asking in general purpose channels like [#frontend](https://gitlab.slack.com/messages/C0GQHHPGW/), [#backend](https://gitlab.slack.com/messages/C8HG8D9MY/), [#development](https://gitlab.slack.com/messages/C02PF508L/) or [#questions](https://gitlab.slack.com/messages/C0AR2KW4B/).
#### Numbering is for reference, not as a signal
......
......@@ -39,7 +39,7 @@ You'll need to think creatively, speak up to see how you can help, and be willin
### Freedom to iterate
At GitLab, our [value of iteration]({{< ref "values#iteration" >}}) has a unique impact on the way we operate and get things done.
At GitLab, our [value of iteration](/handbook/values/#iteration) has a unique impact on the way we operate and get things done.
Working this way means our team members are expected to quickly deliver the minimum viable change in their work instead of waiting to produce a polished, completed product.
......
......@@ -149,7 +149,7 @@ The importance of [strong documentation]({{< ref "./handbook-first" >}}) for asy
GitLab has a [handbook-first]({{< ref "handbook-usage#why-handbook-first" >}}) approach to all communication. Our goal is to ensure that our handbook is always up to date and that it is a powerful resource to make our team massively more efficient. The [GitLab handbook](/handbook) would be over 2,000 pages if printed, and it is available to read for any visitor who wants to know how we work.
While you may not choose to have this level of transparency, be aware that [transparent information-sharing]({{< ref "values#transparency" >}}) within your organization is crucial to asynchronous work. Every team member should be empowered to do their work at any time, whether or not their teammates are online and available.
While you may not choose to have this level of transparency, be aware that [transparent information-sharing](/handbook/values/#transparency) within your organization is crucial to asynchronous work. Every team member should be empowered to do their work at any time, whether or not their teammates are online and available.
#### Using GitLab for remote collaboration
......@@ -161,7 +161,7 @@ You can learn more at GitLab's [remote team solutions page]({{< ref "gitlab-for-
### When to use asynchronous instead of synchronous communication
While GitLab has [a bias towards asynchronous communication]({{< ref "values#bias-towards-asynchronous-communication" >}}), a strategic balance between synchronous and asynchronous is useful for achieving maximum [efficiency]({{< ref "values#efficiency" >}}). Working asynchronously is not a goal unto itself; rather, being considerate and opting to move a discussion or project forward asynchronously when feasible *creates* more space for synchronous moments.
While GitLab has [a bias towards asynchronous communication]({{< ref "values#bias-towards-asynchronous-communication" >}}), a strategic balance between synchronous and asynchronous is useful for achieving maximum [efficiency](/handbook/values/#efficiency). Working asynchronously is not a goal unto itself; rather, being considerate and opting to move a discussion or project forward asynchronously when feasible *creates* more space for synchronous moments.
Highly capable asynchronous work still allows for, and includes at appropriate moments, some synchronous discussion. Async is very powerful for GitLab, but not an absolute — especially if at the expense of our [values]({{< ref "values" >}}).
......@@ -171,7 +171,7 @@ At GitLab, if you schedule a work-related meeting (e.g. not a [coffee chat]({{<
If you are creating double work for yourself or others — holding a meeting simply to document what will need to be written down in order to [work handbook-first]({{< ref "handbook-usage#why-handbook-first" >}}) — it is likely more efficient to not hold a meeting and instead work asynchronously.
When considering meetings, review the GitLab value of [Efficiency]({{< ref "values#efficiency" >}}) and following the meeting guidelines in [being respectful of others' time]({{< ref "values#be-respectful-of-others-time" >}}). Do not schedule a coffee chat which is a work-related meeting in disguise.
When considering meetings, review the GitLab value of [Efficiency](/handbook/values/#efficiency) and following the meeting guidelines in [being respectful of others' time]({{< ref "values#be-respectful-of-others-time" >}}). Do not schedule a coffee chat which is a work-related meeting in disguise.
## How to implement asynchronous workflows
......@@ -183,7 +183,7 @@ This removes the temptation to take shortcuts, or to call a [meeting]({{< ref ".
### Focus on iteration
Practicing [iteration 👣]({{< ref "values#iteration" >}}) at GitLab requires intention and effort. It is often referred to as the most difficult [value](/handbook/values/) to embrace. Iterating on numerous ongoing projects is an ideal forcing function to ensure a [bias toward asynchronous communication]({{< ref "values#bias-towards-asynchronous-communication" >}}).
Practicing [iteration 👣](/handbook/values/#iteration) at GitLab requires intention and effort. It is often referred to as the most difficult [value](/handbook/values/) to embrace. Iterating on numerous ongoing projects is an ideal forcing function to ensure a [bias toward asynchronous communication]({{< ref "values#bias-towards-asynchronous-communication" >}}).
Asynchronous work can feel taxing and inefficient if you're only working on a single project and you're stuck waiting for another person's contribution. Scheduling your work so you can pick up other tasks while waiting to be unblocked can reduce this downtime.
......@@ -310,10 +310,10 @@ Examples:
At GitLab, we have a [bias towards asynchronous communication]({{< ref "#bias-towards-asynchronous-communication" >}}). As a meeting participant, whether you are scheduling or an invitee, question every work-related meeting.
1. What is the outcome I am trying to achieve that has led to my desire to schedule a meeting?
1. Can the desired outcome be broken down into [smaller tasks]({{< ref "values#iteration" >}})?
1. Can the desired outcome be broken down into [smaller tasks](/handbook/values/#iteration)?
1. Can the desired outcome be achieved or worked towards by [dogfooding](/handbook/engineering/development/principles/#dogfooding) and using a [GitLab issue](https://docs.gitlab.com/ee/user/project/issues/) or [merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)?
1. Am I trying to gather consensus? (*If so, this can be done asynchronously*.)
1. Am I trying to make a decision after consensus is gathered and there is a [proposal]({{< ref "#make-a-proposal" >}}) to react to? (If so, a meeting may be acceptable if it cannot be agreed upon asynchronously, but remember that outcomes must [still be documented in the handbook]({{< ref "handbook-usage#why-handbook-first" >}}). If your outcome(s) will be documented in the end, it calls into question the [efficiency]({{< ref "values#efficiency" >}}) of a synchronous meeting.)
1. Am I trying to make a decision after consensus is gathered and there is a [proposal]({{< ref "#make-a-proposal" >}}) to react to? (If so, a meeting may be acceptable if it cannot be agreed upon asynchronously, but remember that outcomes must [still be documented in the handbook]({{< ref "handbook-usage#why-handbook-first" >}}). If your outcome(s) will be documented in the end, it calls into question the [efficiency](/handbook/values/#efficiency) of a synchronous meeting.)
### When to start synchronously
......@@ -506,7 +506,7 @@ GitLab team members may question meetings, suggesting an asynchronous alternativ
1. Conduct an asynchronous pilot. This could mean attending half of your weekly meetings async for a week and conducting a retrospective on the differences between sync attendance and async attendance.
1. Conduct a [non-linear workday]({{< ref "./non-linear-workday" >}}) pilot. Consider shifting your schedule to better suit your peak productivity hours, caregiving hours, or experiment with alternative work schedules that would not be supported in rigidly synchronous organizations.
1. For any given piece of work, seek to optimize the mix of synchronous and asynchronous engagements for maximum [efficiency]({{< ref "values#efficiency" >}}) and potential for [iteration]({{< ref "values#iteration" >}}).
1. For any given piece of work, seek to optimize the mix of synchronous and asynchronous engagements for maximum [efficiency](/handbook/values/#efficiency) and potential for [iteration](/handbook/values/#iteration).
1. Team members have varying learning and communication style preferences (e.g. [neurodiversity]({{< ref "values#embracing-neurodiversity" >}})) that make audio discussion much more effective than written. Thoughtfully timed synchronous discussions ensure that everyone can contribute.
1. Every meeting should be [a review of a concrete proposal]({{< ref "values#make-a-proposal" >}}) or to catalyze a future series of asynchronous events, and only called when it will lead to a more efficient outcome than would be possible asynchronously.
1. An initial team-building sync at the start of a project or milestone can unlock a highly efficient follow-on series of asynchronous events. Be mindful to structure these initial syncs intentionally to build rapport and trust. The goal of gathering the group in a shared space should be unambiguous: it serves to equip team members with the context they need to switch primarily to asynchronous afterwards. Note that even these intentionally structured kickoff calls may not be inclusive of all time zones. Thus, it is important to adhere to GitLab's [meeting guidelines]({{< ref "communication#scheduling-meetings" >}}), affixing a Google Doc agenda to the calendar invite, encourging all parties to contribute textually if they cannot attend in person, and recording the full session for future viewing.
......@@ -539,13 +539,13 @@ Responses are open to interpretation, though the data provide key insights that
1. GitLab is [public by default]({{< ref "values#public-by-default" >}}). If you believe a matter is confidential, check this in the [Not Public]({{< ref "confidentiality-levels#not-public" >}}) section of the Communication handbook.
1. If you find it difficult to get someone's attention via asynchronous means, consider leveraging a synchronous engagement to discuss potential gaps in expectations. While GitLab is articulate about where work happens, some team members work exclusively from [GitLab's To-Do List](https://docs.gitlab.com/ee/user/todos.html) or Scoped Labels and have varying approaches to prioritization (*see Brand and Digital Design's [Working With Us](/handbook/marketing/digital-experience/#working-with-us) handbook for an example*). Assume positive intent, as delays in response may be attributable to putting [family and friends first]({{< ref "values#family-and-friends-first-work-second" >}}).
1. The majority of respondents indicated that they leverage synchronous engagements to build rapport and catalyze future async conversations. Having a meeting not because it's *easy*, but because it will create *future efficiencies and cohesion*, is a positive outcome.
1. It is encouraging that GitLab team members feel that they have the tools, support, and training to rely on asynchronous workflows. However, leaders should be mindful of new tools and practices that GitLab can pilot and surface these in the public `#values` Slack channel. [Iteration]({{< ref "values#iteration" >}}) also applies to our approach to asynchronous communication.
1. It is encouraging that GitLab team members feel that they have the tools, support, and training to rely on asynchronous workflows. However, leaders should be mindful of new tools and practices that GitLab can pilot and surface these in the public `#values` Slack channel. [Iteration](/handbook/values/#iteration) also applies to our approach to asynchronous communication.
#### GitLab experts advise on when to use sync vs async
1. "I use sync meetings to help others when an urgent matter comes up such as incidents or deadlines."
1. "I use sync mainly for troubleshooting where more live dialog is faster for all parties to solve the particular issue than async explanations and back and forth."
1. "I use sync when I have exhausted async options or async is not leading towards [Results]({{< ref "values#results" >}})."
1. "I use sync when I have exhausted async options or async is not leading towards [Results](/handbook/values/#results)."
1. "I use sync meetings to generate creative ideas/proposals with my team that quite frankly would be difficult to do async."
1. "10 minutes on Zoom is more efficient than 100 Slack replies over a few hours or 10 days waiting for GitLab issue thread replies from tagged team members."
1. "For work-related, formal comms, I prefer async (and choose async when the format is up to me). Sync is great for relationship building (coffee chats, group social chats)."
......
......@@ -24,7 +24,7 @@ Managing remotely is much like managing in-person, but there are certain traits
### Self-awareness
Self-awareness is critical for relationship building and trust, particularly in an all-remote setting. The reality is that people prefer to learn, and to be managed, differently. GitLab's CEO goes so far as to [publicize his communication preferences](/handbook/ceo#communication) and [flaws](/handbook/ceo#flaws), which requires a high degree of self-awareness, a [low level of shame]({{< ref "values#low-level-of-shame" >}}), and a penchant for [transparency]({{< ref "values#transparency" >}}).
Self-awareness is critical for relationship building and trust, particularly in an all-remote setting. The reality is that people prefer to learn, and to be managed, differently. GitLab's CEO goes so far as to [publicize his communication preferences](/handbook/ceo#communication) and [flaws](/handbook/ceo#flaws), which requires a high degree of self-awareness, a [low level of shame]({{< ref "values#low-level-of-shame" >}}), and a penchant for [transparency](/handbook/values/#transparency).
Self-aware managers will be open with reports on their learning and communication preferences, enabling those who report to them to interact without ambiguity.
......@@ -72,7 +72,7 @@ Use weekly [1-1 meetings]({{< ref "1-1" >}}) to discuss business topics, challen
Not everyone is capable of going fully-remote or mentally prepared to go days without a human interaction. Set up regular video chats and be sure to make space for [intentional informal communication]({{< ref "./informal-communication" >}}).
Being a remote manager means building a support system for your team, while at the same time striking a balance to hold them accountable. [Building trust]({{< ref "building-trust" >}}), maintaining [transparency]({{< ref "values#transparency" >}}), communicating frequently and openly, and ensuring a supportive working environment are critical for success.
Being a remote manager means building a support system for your team, while at the same time striking a balance to hold them accountable. [Building trust]({{< ref "building-trust" >}}), maintaining [transparency](/handbook/values/#transparency), communicating frequently and openly, and ensuring a supportive working environment are critical for success.
#### Maintain constant communication
......@@ -155,7 +155,7 @@ The manager should be intentional about selecting an onboarding buddy. Aim to se
### Balance self-learning and nurturing
In a remote setting, it's vital that a new hire recognize the importance of [working handbook-first]({{< ref "./handbook-first" >}}). This reality needs to be balanced with nurturing — an empathetic approach to working with a colleague. During onboarding, ask for feedback on this. A manager should be willing and able to adapt to a new hire's preferred communication methods, and be willing to [iterate]({{< ref "values#iteration" >}}) on this.
In a remote setting, it's vital that a new hire recognize the importance of [working handbook-first]({{< ref "./handbook-first" >}}). This reality needs to be balanced with nurturing — an empathetic approach to working with a colleague. During onboarding, ask for feedback on this. A manager should be willing and able to adapt to a new hire's preferred communication methods, and be willing to [iterate](/handbook/values/#iteration) on this.
## How do you motivate remote workers?
......@@ -175,7 +175,7 @@ GitLab's expertise in managing a remote team has been turned into a free course
## Red flags to watch out for
Despite its many [advantages]({{< ref "./remote-benefits" >}}), all-remote work isn't for everyone. It can have disadvantages for potential employees depending on their lifestyle and work preferences, as well as the organization. In the spirit of [transparency]({{< ref "values#transparency" >}}), we'll also highlight counterpoints and solutions to these challenges.
Despite its many [advantages]({{< ref "./remote-benefits" >}}), all-remote work isn't for everyone. It can have disadvantages for potential employees depending on their lifestyle and work preferences, as well as the organization. In the spirit of [transparency](/handbook/values/#transparency), we'll also highlight counterpoints and solutions to these challenges.
### Loneliness and isolation
......@@ -215,7 +215,7 @@ A natural inclination when managing a team is to manage people — the *individu
To better understand how this impacts management style, consider this example. Each time a manager is asked a question by a direct report, there is a loss of productivity and focus in answering. If this answer is delivered verbally and privately, its benefit is highly specific and ephemeral. If, however, the manager considers the answer, documents it in a searchable location, and [answers with a link]({{< ref "./self-service#answer-with-a-link" >}}), the process of answering becomes far more useful long-term.
In the latter case, this act of managing a *process* instead of a *person* creates outsized long-term [efficiency]({{< ref "values#efficiency" >}}). Every future direct report who has the same question will now be able to side-step the interruption and locate the answer themselves, creating two positive loops in the process.
In the latter case, this act of managing a *process* instead of a *person* creates outsized long-term [efficiency](/handbook/values/#efficiency). Every future direct report who has the same question will now be able to side-step the interruption and locate the answer themselves, creating two positive loops in the process.
One, new hires recognize that they are [empowered to search for answers]({{< ref "./self-service" >}}), securing important information to keep projects moving even when their manager is on vacation, out of the office, or engaged in other work. This should lead to fewer blockers, less [dysfunction]({{< ref "values#five-dysfunctions" >}}), greater [autonomy]({{< ref "values#give-agency" >}}), improved [mental health]({{< ref "./mental-health" >}}), and greater productivity.
......@@ -229,11 +229,11 @@ Two, managers carve out more bandwidth in their day to focus, rather than re-ans
It is the job of a manager to ensure a direct report has what they need to be successful on an ongoing basis. By [documenting]({{< ref "./management#scaling-by-documenting" >}}) processes, guides, solutions, how-tos, and policies, a manager is practicing [servant leadership](https://www.shrm.org/resourcesandtools/hr-topics/organizational-and-employee-development/pages/the-art-of-servant-leadership.aspx) in a powerful way.
If your company has yet to implement their own handbook, start now and start small. Don't be overwhelmed with the notion of building a complete handbook from the get-go; simply start with one process, then document the next, and so on. This is the power of [iteration]({{< ref "values#iteration" >}}). GitLab (the company) uses GitLab ([the product](https://about.gitlab.com/stages-devops-lifecycle/)) to build and maintain our public-facing [handbook](/handbook), and options from [Almanac](https://almanac.io/) and [Trainual](https://trainual.com/) are available as well.
If your company has yet to implement their own handbook, start now and start small. Don't be overwhelmed with the notion of building a complete handbook from the get-go; simply start with one process, then document the next, and so on. This is the power of [iteration](/handbook/values/#iteration). GitLab (the company) uses GitLab ([the product](https://about.gitlab.com/stages-devops-lifecycle/)) to build and maintain our public-facing [handbook](/handbook), and options from [Almanac](https://almanac.io/) and [Trainual](https://trainual.com/) are available as well.
In the event that a direct report asks a question that has yet to be documented, agree to document the eventual solution so that the work put forth in answering benefits a wider swath of people.
By embracing a documentarian mindset as a manager, you show that you are proactively and [transparently]({{< ref "values#transparency" >}}) working to equip your direct report(s) with everything they need to succeed.
By embracing a documentarian mindset as a manager, you show that you are proactively and [transparently](/handbook/values/#transparency) working to equip your direct report(s) with everything they need to succeed.
This may feel as if it's placing an added burden on a manager. The reality is that short-term pangs derived from time spent on documenting will be greatly overshadowed by long-term efficiencies. If you, as a manager, believe that you "simply don't have time to document," pause and consider the current scenario from a perspective involving more than yourself.
......@@ -286,7 +286,7 @@ To improve managerial productivity:
1. Prioritize tasks and have a clear expectation of what everyone is working on with due dates.
1. Use GitLab Issues and Merge Requests to track work.
With GitLab's commitment to [transparency]({{< ref "values#results" >}}), team members have a great deal of visibility to what is going on throughout the organization. A manager's role is to focus the team on cross-functional activities relevant to their [results]({{< ref "values#results" >}}).
With GitLab's commitment to [transparency](/handbook/values/#results), team members have a great deal of visibility to what is going on throughout the organization. A manager's role is to focus the team on cross-functional activities relevant to their [results](/handbook/values/#results).
## How to engage remote employees
......
......@@ -41,7 +41,7 @@ It starts by being intentional about [informal communication]({{< ref "./informa
*In the [video](https://youtu.be/IU2nTj6NSlQ) above, GitLab's Head of Remote discusses the topic of scaling culture during an interview with [Stuart Miniman](https://twitter.com/stu/), host of [theCUBE](https://www.thecube.net/) and GM of Content at [SiliconANGLE Media](https://siliconangle.com/).
It's challenging to build and maintain a healthy remote culture. Despite its [advantages]({{< ref "./remote-benefits" >}}), all-remote work isn't for everyone. It can have disadvantages as well. In the spirit of [transparency]({{< ref "values#transparency" >}}), here are some of the [challenges and solutions to maintaining remote work culture](./drawbacks/).
It's challenging to build and maintain a healthy remote culture. Despite its [advantages]({{< ref "./remote-benefits" >}}), all-remote work isn't for everyone. It can have disadvantages as well. In the spirit of [transparency](/handbook/values/#transparency), here are some of the [challenges and solutions to maintaining remote work culture](./drawbacks/).
## Culture looks different in a pandemic
......@@ -67,7 +67,7 @@ As leaders and team members were grappling with going remote, the pandemic force
## Why inclusion matters more than ever
GitLab believes that combining many perspectives creates a more innovative environment to work in, with more satisfied teammates, leading to a better product and increased profitability. [Diversity, Inclusion & Belonging]({{< ref "values#diversity-inclusion" >}}) is one of our company values.
GitLab believes that combining many perspectives creates a more innovative environment to work in, with more satisfied teammates, leading to a better product and increased profitability. [Diversity, Inclusion & Belonging](/handbook/values/#diversity-inclusion) is one of our company values.
Inclusion allows us to recognize, respect, and value differences in those around us. Being inclusive requires skills such as empathy, openness, and listening. Inclusion also means we are keenly aware of both [positive and negative biases]({{< ref "unconscious-bias" >}}) and how those biases impact our daily interactions, work, and employee retention.
......@@ -136,7 +136,7 @@ Remote [interviewers]({{< ref "./interviews" >}}) should link a company's values
![GitLab values illustration](/images/all-remote/gitlab-values-tanukis.jpg)
{style="max-width: 50%;"}
There should be no unwritten rules in remote culture. Intentional documentation is essential to avoiding [dysfunction]({{< ref "values#five-dysfunctions" >}}) within a remote company, and this also applies to culture. At GitLab, this begins with our company values: [Collaboration]({{< ref "values#collaboration" >}}), [Results]({{< ref "values#results" >}}), [Efficiency]({{< ref "values#efficiency" >}}), [Diversity, Inclusion & Belonging]({{< ref "values#diversity-inclusion" >}}), [Iteration]({{< ref "values#iteration" >}}), and [Transparency]({{< ref "values#transparency" >}}).
There should be no unwritten rules in remote culture. Intentional documentation is essential to avoiding [dysfunction]({{< ref "values#five-dysfunctions" >}}) within a remote company, and this also applies to culture. At GitLab, this begins with our company values: [Collaboration](/handbook/values/#collaboration), [Results](/handbook/values/#results), [Efficiency](/handbook/values/#efficiency), [Diversity, Inclusion & Belonging](/handbook/values/#diversity-inclusion), [Iteration](/handbook/values/#iteration), and [Transparency](/handbook/values/#transparency).
**Culture is best defined not by how a company or team acts when all is well; rather, by the behaviors shown during times of crisis or duress**.
......@@ -186,7 +186,7 @@ A healthy remote work environment clearly defines its culture and expectations.
Be open about as many things as possible by making information public. This transparency helps reduce confusion and makes collaboration easier. Use public issue trackers, projects, and repositories when possible.
[Transparency]({{< ref "values#transparency" >}}) creates awareness for GitLab. It does that by allowing us to recruit people that care about our values, gets us more and faster feedback from people outside the company, and makes it easier to collaborate with them. It also helps us share great software, documentation, examples, lessons, and processes in the spirit of open source, which we believe creates more value than it captures.
[Transparency](/handbook/values/#transparency) creates awareness for GitLab. It does that by allowing us to recruit people that care about our values, gets us more and faster feedback from people outside the company, and makes it easier to collaborate with them. It also helps us share great software, documentation, examples, lessons, and processes in the spirit of open source, which we believe creates more value than it captures.
### Continually promote and enhance work-life balance and flexibility
......@@ -216,7 +216,7 @@ This creates an environment where your [mental health]({{< ref "./mental-health"
## The importance of gratitude and transparency
Persistent negativity can erode culture. While [feedback]({{< ref "guidance-on-feedback" >}}) is a gift, there's a fine line between reacting with hope and determination when facing a challenge and allowing a sense of apathy or dread to permeate a company. Leaders should be cognizant of this and act swiftly if there's a noted drop in outward gratitude or [transparency]({{< ref "values#transparency" >}}) in communications.
Persistent negativity can erode culture. While [feedback]({{< ref "guidance-on-feedback" >}}) is a gift, there's a fine line between reacting with hope and determination when facing a challenge and allowing a sense of apathy or dread to permeate a company. Leaders should be cognizant of this and act swiftly if there's a noted drop in outward gratitude or [transparency](/handbook/values/#transparency) in communications.
{{< youtube "cy6WGuzArgY?start=232" >}}
......
......@@ -7,7 +7,7 @@ twitter_site: "@gitlab"
twitter_creator: "@gitlab"
---
Despite all of its [advantages]({{< ref "remote-benefits" >}}), all-remote work isn't for everyone. It can have disadvantages for potential employees depending on their lifestyle and work preferences, as well as the organization. In the spirit of [transparency]({{< ref "values#transparency" >}}), we'll also highlight counterpoints and solutions to these challenges.
Despite all of its [advantages]({{< ref "remote-benefits" >}}), all-remote work isn't for everyone. It can have disadvantages for potential employees depending on their lifestyle and work preferences, as well as the organization. In the spirit of [transparency](/handbook/values/#transparency), we'll also highlight counterpoints and solutions to these challenges.
{{< youtube "CwOLAKSdlfs" >}}
......@@ -76,7 +76,7 @@ It can be hard to separate your personal and work life. It's important to encour
**Solutions**
- [Preventing a culture of burnout starts at the top](https://about.gitlab.com/blog/2018/03/08/preventing-burnout/). In all-remote companies, it's important to reinforce this from the [interview process](https://about.gitlab.com/blog/2019/03/28/what-its-like-to-interview-at-gitlab/), to [onboarding]({{< ref "./learning-and-development#how-do-you-onboard-new-team-members" >}}), to regular [1:1s]({{< ref "1-1" >}}).
- All-remote companies should consider implementing a [Results value]({{< ref "values#results" >}}), where [results (as opposed to hours) are measured]({{< ref "values#measure-results-not-hours" >}}). Fundamentally, this requires organizational trust — believing that colleagues will do the right thing rather than implementing rigid rules.
- All-remote companies should consider implementing a [Results value](/handbook/values/#results), where [results (as opposed to hours) are measured]({{< ref "values#measure-results-not-hours" >}}). Fundamentally, this requires organizational trust — believing that colleagues will do the right thing rather than implementing rigid rules.
- At GitLab, we encourage team members to [communicate with their manager when they recognize burnout]({{< ref "paid-time-off#recognizing-burnout" >}}), and to be mindful of the last time a team member [took time off from work]({{< ref "paid-time-off#paid-time-off" >}}).
### Challenge: Time management
......
......@@ -45,7 +45,7 @@ Because of the self-directed nature of remote work, employers look for people ca
- working [asynchronously]({{< ref "./asynchronous" >}})
- [communicating through text]({{< ref "./effective-communication" >}})
- setting up an ideal [workspace]({{< ref "./workspace" >}})
- eliminating distractions for optimal [efficiency]({{< ref "values#efficiency" >}})
- eliminating distractions for optimal [efficiency](/handbook/values/#efficiency)
![GitLab collaboration illustration](/images/all-remote/gitlab-collaboration-illustration.jpg)
{style="max-width: 50%;"}
......@@ -54,7 +54,7 @@ Because of the self-directed nature of remote work, employers look for people ca
### Q: Where does leadership work?
When evaluating a remote role, it's critical to understand where leadership works on a day-to-day basis. In an all-remote company, each team member — including the executive team — is remote. This creates a culture of trust and [transparency]({{< ref "values#transparency" >}}), and it sends a clear message that no one will be treated as an outsider within the organization based on their geographic location.
When evaluating a remote role, it's critical to understand where leadership works on a day-to-day basis. In an all-remote company, each team member — including the executive team — is remote. This creates a culture of trust and [transparency](/handbook/values/#transparency), and it sends a clear message that no one will be treated as an outsider within the organization based on their geographic location.
In companies where the leadership team is colocated, but most (if not all) of the company is remote, consider asking how this impacts the dissemination of information. Remote [forces companies to do things they ought to be doing earlier and better]({{< ref "./management#how-do-you-manage-a-100-remote-team" >}}), including [documenting]({{< ref "documentation" >}}) culture and process. With a colocated leadership team, a company runs the risk of bypassing diligent documentation in favor of an in-person sync where discussion notes and outcomes are not documented and shared.
......@@ -71,7 +71,7 @@ This ensures that each team member is treated equally, and removes typical board
Flex-work and workplace flexibility have grown in popularity, but it's important to ask for specific examples of how this actually works within a company you are considering joining.
Do only senior leaders have complete flexibility to schedule their working hours and days around their lives? Is workplace flexibility truly embraced and supported throughout the organization? Does the company empower team members to be a [manager of one]({{< ref "values#managers-of-one" >}}), valuing [outputs]({{< ref "values#results" >}}) rather than inputs such as hours worked?
Do only senior leaders have complete flexibility to schedule their working hours and days around their lives? Is workplace flexibility truly embraced and supported throughout the organization? Does the company empower team members to be a [manager of one]({{< ref "values#managers-of-one" >}}), valuing [outputs](/handbook/values/#results) rather than inputs such as hours worked?
When life happens and you need to restructure your day on the fly, is this openly encouraged and supported or quietly frowned upon?
......
......@@ -92,8 +92,8 @@ If you're a founder or hiring manager, these events offer a platform to promote
As remote work becomes more popular, a number of conferences and summits are emerging to serve a few key purposes.
1. Educate the world on the [power]({{< ref "./remote-benefits" >}}) and [efficiency]({{< ref "values#efficiency" >}}) of working remotely, including those who have not yet embraced remote work.
1. Bring remote workers and companies together to fuel [collaboration]({{< ref "values#collaboration" >}}) and share learnings.
1. Educate the world on the [power]({{< ref "./remote-benefits" >}}) and [efficiency](/handbook/values/#efficiency) of working remotely, including those who have not yet embraced remote work.
1. Bring remote workers and companies together to fuel [collaboration](/handbook/values/#collaboration) and share learnings.
1. Provide a platform for experts to share knowledge with the [broader remote work community]({{< ref "./jobs" >}}).
1. Create a tighter, more unified network of all-remote and remote-first advocates to evangelize for the creation of [more remote roles]({{< ref "./hiring" >}}).
......
......@@ -150,7 +150,7 @@ Below are a number of intentional facets of [GitLab's culture](/handbook/company
Spend time getting to know [GitLab's publicly viewable handbook](/handbook), which captures everything you need to know about the company.
Technology is ever-changing. Which is one reason why GitLab's [onboarding process]({{< ref "./onboarding" >}}) includes exercises in self-service via an [onboarding issue]({{< ref "general-onboarding" >}}) with multiple tasks broken down into small, digestible chunks. Each issue guides new hires to complete certain tasks on certain days, being a [manager of one]({{< ref "values#managers-of-one" >}}) — an operating principle of [Efficiency]({{< ref "values#efficiency" >}}) — applies from the very beginning.
Technology is ever-changing. Which is one reason why GitLab's [onboarding process]({{< ref "./onboarding" >}}) includes exercises in self-service via an [onboarding issue]({{< ref "general-onboarding" >}}) with multiple tasks broken down into small, digestible chunks. Each issue guides new hires to complete certain tasks on certain days, being a [manager of one]({{< ref "values#managers-of-one" >}}) — an operating principle of [Efficiency](/handbook/values/#efficiency) — applies from the very beginning.
### Develop a schedule that you can initially follow
......
......@@ -12,7 +12,7 @@ twitter_creator: "@gitlab"
A [handbook-first]({{< ref "handbook-usage#why-handbook-first" >}}) approach to communication is [sneakily vital]({{< ref "./management#scaling-by-documenting" >}}) to a well-run business. While it feels skippable — inefficient, even — the outsized benefits of intentionally writing down and organizing process, [culture]({{< ref "./building-culture" >}}), and solutions are staggering. Conversely, *avoiding* structured documentation is the best way to instill a low-level sense of [chaos and confusion]({{< ref "values#five-dysfunctions" >}}) that hampers growth across the board.
GitLab is intentional about documenting in a manner that creates a [single source of truth]({{< ref "values#single-source-of-truth" >}}). It operates [handbook-first]({{< ref "handbook-usage#why-handbook-first" >}}), and in valuing [transparency]({{< ref "values#transparency" >}}), makes its handbook [publicly accessible to all](/handbook).
GitLab is intentional about documenting in a manner that creates a [single source of truth]({{< ref "values#single-source-of-truth" >}}). It operates [handbook-first]({{< ref "handbook-usage#why-handbook-first" >}}), and in valuing [transparency](/handbook/values/#transparency), makes its handbook [publicly accessible to all](/handbook).
## Terminology (documentation, handbook-first, single source of truth)
......@@ -31,7 +31,7 @@ As a team scales, the **need** for documentation increases in parallel with the
Documentation is rarely placed on the same pedestal with metrics such as sales and client retention during a company's formative years, but it [deserves to be]({{< ref "./self-service" >}}). The difference between a well-documented company and one that eschews a handbook is stark.
A handbook-first organization is home to team members who benefit from having a [single source of truth]({{< ref "values#single-source-of-truth" >}}) to lean on. This type of organization is able to operate with almost supernatural [efficiency]({{< ref "values#efficiency" >}}). An organization that does *not* put concerted effort into structured documentation has no choice but to watch its team members ask and re-ask for the same bits of data in perpetuity, creating a torturous loop of interruptions, meetings, and suboptimal knowledge transfers.
A handbook-first organization is home to team members who benefit from having a [single source of truth]({{< ref "values#single-source-of-truth" >}}) to lean on. This type of organization is able to operate with almost supernatural [efficiency](/handbook/values/#efficiency). An organization that does *not* put concerted effort into structured documentation has no choice but to watch its team members ask and re-ask for the same bits of data in perpetuity, creating a torturous loop of interruptions, meetings, and suboptimal knowledge transfers.
## Start now
......@@ -57,7 +57,7 @@ It's difficult to rally an organization to only use Slack for [informal communic
There's a very real fear that instilling a culture of "handbook first" is too tall a task to actually accomplish. The goal should **not** be to complete the handbook before ever announcing its existence to the company.
For established organizations, the trick is to apply [iteration]({{< ref "values#iteration" >}}) to the challenge of standing up a handbook within a company. Put the proper infrastructure in place (which we'll cover below), and begin documenting process after process, one at a time. Building a handbook well after a firm's infancy is tough, as you're changing both process and culture while operating a business at scale. However, leaders can manage expectations to make the handbook's insertion easier to understand profoundly through intuition or empathy.
For established organizations, the trick is to apply [iteration](/handbook/values/#iteration) to the challenge of standing up a handbook within a company. Put the proper infrastructure in place (which we'll cover below), and begin documenting process after process, one at a time. Building a handbook well after a firm's infancy is tough, as you're changing both process and culture while operating a business at scale. However, leaders can manage expectations to make the handbook's insertion easier to understand profoundly through intuition or empathy.
## Documentation is never finished
......@@ -103,7 +103,7 @@ This enables anyone at the company, even those who have just joined, to propose
1. In [this merge request](https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/29227), only a portion of the initial proposal was agreed upon and merged into GitLab's handbook. However, this ensured that all pertinent parties had a voice. This also documents the thought process that went into the eventual documentation, such that [context]({{< ref "./effective-communication#understanding-low-context-communication" >}}) is in place for anyone to understand why these changes were made, and when.
1. By empowering all team members to make proposals, you enable new hires to offer up fresh perspectives that can benefit the company. [This merge request](https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/29045) is an example of a new hire sharing a proposal to strengthen GitLab's [Onboarding Buddy]({{< ref "onboarding-buddies" >}}) checklist, and then her buddy made a proposal which was eventually merged.
1. This [merge request](https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/36848) was proposed by someone still in the onboarding phase at GitLab. The discussion threads offer visibility into how learning happens, how [iteration]({{< ref "values#iteration" >}}) shapes proposals, and how [everyone can contribute](/handbook/company/strategy#why) to the handbook's evolution.
1. This [merge request](https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/36848) was proposed by someone still in the onboarding phase at GitLab. The discussion threads offer visibility into how learning happens, how [iteration](/handbook/values/#iteration) shapes proposals, and how [everyone can contribute](/handbook/company/strategy#why) to the handbook's evolution.
## What goes in a company handbook?
......@@ -131,7 +131,7 @@ The beauty of using a tool like [GitLab](https://about.gitlab.com/stages-devops-
- Standard operating procedures
- Monthly or quarterly goals
Most sections will be blank to begin with, and that's OK. Apply the spirit of [iteration]({{< ref "values#iteration" >}}) to documentation. Rather than judging a section for how light it is, praise a contributor for making it [marginally better]({{< ref "values#minimal-viable-change-mvc" >}}) than it was prior.
Most sections will be blank to begin with, and that's OK. Apply the spirit of [iteration](/handbook/values/#iteration) to documentation. Rather than judging a section for how light it is, praise a contributor for making it [marginally better]({{< ref "values#minimal-viable-change-mvc" >}}) than it was prior.
## Make handbook-first a value
......@@ -149,7 +149,7 @@ The trick to ensuring a handbook grows continually is to instill it as a value.
>
> This is going slow to go fast. Lots of energy up front — you go slow — but that accelerates things dramatically a year or so down the road. — *[Gabe W.](https://gitlab.com/gweaver), Senior Product Manager, GitLab*
[Write things down]({{< ref "values#write-things-down" >}}) is an operating principle of [Efficiency]({{< ref "values#efficiency" >}}) at GitLab. Team members are as likely to see merge requests [put forth](https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/36397) by [e-group]({{< ref "structure#e-group" >}}) members as they are [new hires](https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/36848).
[Write things down]({{< ref "values#write-things-down" >}}) is an operating principle of [Efficiency](/handbook/values/#efficiency) at GitLab. Team members are as likely to see merge requests [put forth](https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/36397) by [e-group]({{< ref "structure#e-group" >}}) members as they are [new hires](https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/36848).
Empowering the entire company to propose changes creates widespread autonomy and [agency]({{< ref "values#give-agency" >}}). This generates a shared responsibility to maintain the pace of documentation through a [pay-it-forward mentality]({{< ref "./self-service#paying-it-forward" >}}).
......
......@@ -185,7 +185,7 @@ Study the links below. They point to various educational sections within the Git
1. Organizational savvy and the ability to garner influence to positively impact the working lives of team members
1. A native visionary and problem solver who seeks outside perspectives, tools, and workflows to continually evolve an organization’s workplace design, culture, and strategy
1. Propensity to form and foster interdepartmental relationships
1. A default to working [transparently]({{< ref "values#transparency" >}}) and with a [low level of shame]({{< ref "values#low-level-of-shame" >}}) is vital given the extreme cross-functional nature of the role
1. A default to working [transparently](/handbook/values/#transparency) and with a [low level of shame]({{< ref "values#low-level-of-shame" >}}) is vital given the extreme cross-functional nature of the role
1. A sound advisor to other executives, guiding decisions through a global and inclusive lens
1. Appreciation for [self-learning and self-service]({{< ref "./self-service" >}})
1. Appreciation for [documentation]({{< ref "./handbook-first" >}}) and knowledge taxomony/codification
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment