Commit 55ec387a authored by Mike Terhar's avatar Mike Terhar
Browse files

update for 2022

parent ce2c0227
Pipeline #613388111 passed with stages
in 22 seconds
.DS_Store
/public
/resources
.hugo_build.lock
image: registry.gitlab.com/brownfield-dev/remote/handbook:v1-3
image: registry.gitlab.com/pages/hugo/hugo_extended:0.101.0
variables:
GIT_SUBMODULE_STRATEGY: recursive
......@@ -15,7 +15,7 @@ test:
only:
- branches
except:
- master
- main
local:review:
image: alpine:latest
......@@ -25,7 +25,7 @@ local:review:
only:
- branches
except:
- master
- main
environment:
name: local
url: http://127.0.0.1:1313
......@@ -41,4 +41,4 @@ pages:
paths:
- public
only:
- master
- main
......@@ -2,22 +2,22 @@
## Using this project
This was created to provide an easy way for anybody to use GitLab to create a handbook to meet the new remote working style.
This was created to provide an easy way for anybody to use GitLab to create a handbook to meet the new remote working style.
GitLab's handbook is part of a larger website and blog project so any attempt to use it as a starting point would be problematic.
GitLab's handbook is part of a larger website and blog project so any attempt to use it as a starting point would be problematic.
This project exists to compensate for that with as little command-line activity as possible. Forks were disabled because they create a relationship between projects. To use this one, please export and import it into your own account.
This project exists to compensate for that with as little command-line activity as possible. Forks were disabled because they create a relationship between projects. To use this one, please export and import it into your own account.
## After importing this project
There are some configurations that need to happen for this to be used for your own purposes.
There are some configurations that need to happen for this to be used for your own purposes.
1. Use the Web IDE to modify the `config.toml` with a fitting title
1. Remove any template content that doesn't belong in your handbook
1. Update the README to contain instructions for contributing pages
1. Use GitLab Pages with the gitlab.io URL until your company DNS
1. Use the Web IDE to modify the `config.toml` with a fitting title
1. Remove any template content that doesn't belong in your handbook
1. Update the README to contain instructions for contributing pages
1. Use GitLab Pages with the gitlab.io URL until your company DNS
If you want to checkout the repo to make local copies and run the local review app, be sure to do:
If you want to checkout the repo to make local copies and run the local review app, be sure to do:
```bash
git clone git@gitlab.com:brownfield-dev/remote/handbook.git
......@@ -27,41 +27,39 @@ git submodule update --init --recursive
The theme is currently in a submodule which needs to be pulled.
If there's an error about "Shortcode 'columns' not found", that means the submodule didn't get fetched. Use `git submodule update` to retrieve that content.
If there's an error about "Shortcode 'columns' not found", that means the submodule didn't get fetched. Use `git submodule update` to retrieve that content.
## Select a workflow
GitLab offers a lot of workflow flexibility depending on the size of your team and type of content in the handbook.
If your handbook is meant to have company confidential information in it, be sure to set the project to private and the "GitLab Pages" accessibility to "Only Project Members" to prevent disclosure.
If your handbook is meant to have company confidential information in it, be sure to set the project to private and the "GitLab Pages" accessibility to "Only Project Members" to prevent disclosure.
Since project configurations and master branch changes are controlled by `Maintainer` roles, be sure to restrict that permission level to individuals authorized to speak for the organization. If these are non-technical personnel, they can use the Merge Request feature to review content without the requirement to do any git commands or fancy technical activity.
Since project configurations and master branch changes are controlled by `Maintainer` roles, be sure to restrict that permission level to individuals authorized to speak for the organization. If these are non-technical personnel, they can use the Merge Request feature to review content without the requirement to do any git commands or fancy technical activity.
The suggested workflow comes from GitLab Flow and follows these steps:
The suggested workflow comes from GitLab Flow and follows these steps:
1. Individual identifies content that needs to be added or changed
1. Individual creates an issue in the project with the change they intend to make (use "content update" template)
1. Individual clicks the `Create Merge Request` button from the issue
1. Individual opens the Merge Request, clicks on `Web IDE` or checkout code if familiar with git
1. Individual creates new pages or updates existing pages
1. Individual `Resolves WIP Status` in Merge Request and assigns to a maintainer
1. Maintainer reviews change in Merge Request screen using the `Changes` tab
1. Maintainer provides feedback on the specific code (comment on a line or section)
1. Individual updates the page as directed or discusses further
1. Maintainer merges the change
1. Individual identifies content that needs to be added or changed
1. Individual creates an issue in the project with the change they intend to make (use "content update" template)
1. Individual clicks the `Create Merge Request` button from the issue
1. Individual opens the Merge Request, clicks on `Web IDE` or checkout code if familiar with git
1. Individual creates new pages or updates existing pages
1. Individual `Resolves WIP Status` in Merge Request and assigns to a maintainer
1. Maintainer reviews change in Merge Request screen using the `Changes` tab
1. Maintainer provides feedback on the specific code (comment on a line or section)
1. Individual updates the page as directed or discusses further
1. Maintainer merges the change
The important part of this flow is that the changes need to be small. Creating many merge request that only incrementally improve the handbook is acceptable. If the net benefit is at all positive, it should be merged and then follow-up issues or MRs created to address any additional content updates.
The important part of this flow is that the changes need to be small. Creating many merge request that only incrementally improve the handbook is acceptable. If the net benefit is at all positive, it should be merged and then follow-up issues or MRs created to address any additional content updates.
The other thing you may notice is that there's no meeting or discussion or concensus building that takes place in the workflow. The individual should be empowered to fix any pages they believe require improvement. Silver license tier has approvals depending on the change.
The other thing you may notice is that there's no meeting or discussion or concensus building that takes place in the workflow. The individual should be empowered to fix any pages they believe require improvement. Silver license tier has approvals depending on the change.
Don't be afraid to flag content as deprecated or invalid or until an update can be created. Deleting content entirely is also good if it's incorrect, but leaving the pages in will serve as a reminder to execute the update.
Don't be afraid to flag content as deprecated or invalid or until an update can be created. Deleting content entirely is also good if it's incorrect, but leaving the pages in will serve as a reminder to execute the update.
### Customize issue templates
In this repositiry is an example issue template for "Change content" which is based on the GitLab issue for requesting a change. This makes a lot of assumptions and parts are likely not applicable. It may make sense to duplicate it for various sections.
These templates are in `.gitlab/issue_templates/` and the filename is used in the dropdown list for creating a new issue.
Adding [quick actions](https://docs.gitlab.com/ee/user/project/quick_actions.html#quick-actions-for-issues-merge-requests-and-epics) to the bottom of the issue can do things like label them or notify a group.
These templates are in `.gitlab/issue_templates/` and the filename is used in the dropdown list for creating a new issue.
###
Adding [quick actions](https://docs.gitlab.com/ee/user/project/quick_actions.html#quick-actions-for-issues-merge-requests-and-epics) to the bottom of the issue can do things like label them or notify a group.
......@@ -5,7 +5,7 @@
padding: 8px 15px;
margin-bottom: 20px;
list-style: none;
background-color: $gray-100;
background-color: #f8f9fa;
border-radius: 4px;
}
.breadcrumb > li {
......@@ -17,8 +17,8 @@
content: "/\00a0";
}
.breadcrumb > .active {
color: $color-link;
color: #0055bb;
}
.breadcrumb a {
color: $color-link;
color: #0055bb;
}
\ No newline at end of file
......@@ -50,16 +50,16 @@ enableGitInfo = true
# Enable 'Edit this page' links for 'doc' page type.
# Disabled by default. Uncomment to enable. Requires 'BookRepo' param.
# Path must point to 'content' directory of repo.
BookEditPath = '-/edit/master/content'
BookEditPath = '-/edit/main/content'
# Added for webide link
# https://gitlab.com/-/ide/project/brownfield-dev/remote/handbook/edit/master/-/content/company/_index.md
# https://gitlab.com/-/ide/project/brownfield-dev/remote/handbook/edit/main/-/content/company/_index.md
# BookRepoHost |
# | BookGroupProject |
# | BookWebIdePath |
BookRepoHost = 'https://gitlab.com'
BookRepoGroupProject = 'brownfield-dev/remote/handbook'
BookWebIdePath = 'edit/master/-/content/'
BookWebIdePath = 'edit/main/-/content/'
# (Optional, default January 2, 2006) Configure the date format used on the pages
# - In git information
......
......@@ -3,9 +3,10 @@ title: Handbook Home
type: docs
---
# Suddenly Remote Handbook
## Suddenly Remote Handbook
{{< columns >}}
## Suddenly Remote
Suddenly changing how an entire organization works is very disruptive and
......@@ -13,7 +14,7 @@ suddenly being unable to share space is a novel problem. Most disaster
recovery plans and business continuity plans lack aspects of continuing
to work when you can't be co-located with co-workers.
See [https://allremote.info](https://allremote.info) for more information.
See [https://allremote.info](https://allremote.info) for more information.
<--->
......@@ -27,7 +28,6 @@ existing templates seemed like a proper starting point, so I created this one.
See the [Handbook Page]({{< relref "company/handbook" >}}) for more information.
{{< /columns >}}
## The Importance of Handbook
The ultimate goal is that non-technical resources could use this template to
......@@ -36,8 +36,8 @@ handbook.
### Wiki Handbooks Don't Scale
At GitLab, like many others, the handbook started as an informal collection of
documents and wikis. The way Wikis work doesn't lend themselves to handbooks for
At GitLab, like many others, the handbook started as an informal collection of
documents and wikis. The way Wikis work doesn't lend themselves to handbooks for
several reasons, which we have outlined on the [Handbook Usage](https://about.gitlab.com/handbook/handbook-usage/#wiki-handbooks-dont-scale) page.
## Getting Started
......@@ -45,20 +45,20 @@ several reasons, which we have outlined on the [Handbook Usage](https://about.gi
This handbook template can be leveraged by anyone in the world by following
these steps. Expect a video walk-through soon.
1. Create a GitLab.com account
1. Create a Group for your company or organization
1. Create a new project in that group
1. Set the new project as `Import project` and choose `GitLab Export`
1. Download the [handbook-project-export.tar.gz](/handbook-project-export.tar.gz) from this site.
1. Name the project `handbook` or something like that
1. Set visibility to `public` if you don't mind the internet watching you build your handbook, keep it `private` otherwise.
1. There are some pre-loaded issues in the project for establishing a workflow and custom domain, complete those
1. Delete the sample content and replace it with your own. Parts of the sample data exist to demonstrate capabilities of the template.
1. Create a GitLab.com account
1. Create a Group for your company or organization
1. Create a new project in that group
1. Set the new project as `Import project` and choose `GitLab Export`
1. Download the [handbook-project-export.tar.gz](/handbook-project-export.tar.gz) from this site.
1. Name the project `handbook` or something like that
1. Set visibility to `public` if you don't mind the internet watching you build your handbook, keep it `private` otherwise.
1. There are some pre-loaded issues in the project for establishing a workflow and custom domain, complete those
1. Delete the sample content and replace it with your own. Parts of the sample data exist to demonstrate capabilities of the template.
## Provide Feedback
If this template lets you down and doesn't make sense, please [provide feedback](https://gitlab.com/brownfield-dev/remote/feedback/-/issues/new)
so we can improve the template for future use. To submit a change to the template or sample content,
use the Fork + Merge Request workflow. Since this is a template project, git history may be rewritten
and issues are part of the template content, so for clarity and ease-of-use the regular workflow is not
supported for this project.
so we can improve the template for future use. To submit a change to the template or sample content,
use the Fork + Merge Request workflow. Since this is a template project, git history may be rewritten
and issues are part of the template content, so for clarity and ease-of-use the regular workflow is not
supported for this project.
......@@ -6,10 +6,10 @@ weight: 1
Describe the organization.
# Mission
## Mission
# Vision
## Vision
# Goals
## Goals
# Leadership
\ No newline at end of file
## Leadership
......@@ -2,4 +2,4 @@
Talk about how people at your company work and live.
Example of GitLab's [Handbook culture page](https://about.gitlab.com/company/culture/).
\ No newline at end of file
Example of GitLab's [Handbook culture page](https://about.gitlab.com/company/culture/).
......@@ -2,4 +2,4 @@
Topics in a style guide typically cover formats for headings, paragraphs, bullets, etc.
The GitLab [Handbook Style Guide](https://about.gitlab.com/handbook/style-guide/) even covers directory naming and links paths.
\ No newline at end of file
The GitLab [Handbook Style Guide](https://about.gitlab.com/handbook/style-guide/) even covers directory naming and links paths.
......@@ -4,6 +4,6 @@ GitLab is the first company the author has ever worked at that elevated values t
## List the values
## Addditional Value Context, Sub-values
## Additional Value Context, Sub-values
### Specific Behaviors for Each Value and Sub-value
\ No newline at end of file
### Specific Behaviors for Each Value and Sub-value
......@@ -5,6 +5,6 @@ weight: 2
bookFlatSection: true
---
# Departments at Company
## Departments at Company
Overview of company structure. Organizational diagrams, etc.
\ No newline at end of file
Overview of company structure. Organizational diagrams, etc.
......@@ -3,6 +3,6 @@ title: Development
weight: 1
---
# Development Team
## Development Team
The software developers.
\ No newline at end of file
The software developers.
......@@ -6,12 +6,11 @@ We dogfood everything. Based on our product principles, it is the Engineering di
An easy antipattern to fall into is to resolve your problem outside of what the product offers. Dogfooding is not:
1. Building a bot outside of GitLab.
1. Writing scripts that leverage the GitLab API (if the functionality is on our roadmap and could be shipped within the GitLab Project).
1. Using a component of GitLab that is part of our components or managed apps.
1. Using templates or repos that are not part of the default UI (having to type or copy-paste to add them).
1. Building a bot outside of GitLab.
1. Writing scripts that leverage the GitLab API (if the functionality is on our roadmap and could be shipped within the GitLab Project).
1. Using a component of GitLab that is part of our components or managed apps.
1. Using templates or repos that are not part of the default UI (having to type or copy-paste to add them).
## Dogfooding Process
Follow the dogfooding process described in the Product Handbook when considering building a tool outside of GitLab.
......@@ -3,4 +3,4 @@ title: Infrastructure
weight: 2
---
# Infrastructure Team
\ No newline at end of file
## Infrastructure Team
......@@ -3,4 +3,4 @@ title: Quality
weight: 3
---
# Quality Team
\ No newline at end of file
## Quality Team
......@@ -3,6 +3,6 @@ title: Security
weight: 4
---
# Security Team
## Security Team
This is related to product security rather than organizational security.
\ No newline at end of file
This is related to product security rather than organizational security.
......@@ -3,4 +3,4 @@ title: Support
weight: 5
---
# Support Team
\ No newline at end of file
## Support Team
......@@ -3,4 +3,4 @@ title: UX
weight: 1
---
# User Experience
\ No newline at end of file
## User Experience
......@@ -3,4 +3,4 @@ title: Finance
weight: 6
---
# Finance
\ No newline at end of file
## Finance
......@@ -2,6 +2,6 @@
title: Information Technology
weight: 5
---
# Information Technology
## Information Technology
## Resources
\ No newline at end of file
## Resources
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment