Consolidate handbook pages on editing the handbook
Current pages
- https://handbook.gitlab.com/handbook/handbook-usage/ - mix of usage guidance/purpose and “how to edit”
- https://about.gitlab.com/handbook/practical-handbook-edits/ - how to with WebIDE, tips
- https://about.gitlab.com/handbook/git-page-update/ - edit using git, preview locally, team page, how to edit
-
https://handbook.gitlab.com/docs/
- Markdown style guide
- Tools
- Shortcodes
Requirements
- Content for editing new handbook
- Keep content on how to edit team page (for now)
- Remove content on how to edit the old handbook (once fully migrated)
- Note: releases, team page, direction still in www-gitlab-com repo
Related onboarding tasks
A list of onboarding tasks related to or mentioning the related pages:
- how to use and search the handbook
- Review our Practical Handbook Edit Examples to learn more about creating new handbook pages.
- Update your photo, social media handles and story on the team page by following the instructions in the handbook. can suggest improvements or changes to the handbook! It's encouraged!
- Read the practical handbook edits handbook to learn more about efficient handbook updates.
Content Ideas
Create handbook page that explains how to edit the handbook, living in handbook.gitlab.com/about/usage-guide or similar
Practical handbook edits
- Describe how to edit a handbook page in
- Written form, step-by-step tutorial
- Record a video and embed it into the tutorial
- Use the Web IDE in the browser for the first iteration (similar to what exists in https://about.gitlab.com/handbook/practical-handbook-edits/
- Future iterations can be local VS Code IDE or other tools
Handbook usage guide
- Move the more tips for find/sed automation from https://about.gitlab.com/handbook/practical-handbook-edits/#more-tips
- Create a section with CI/CD troubleshooting which includes the fix-trailing-whitespace guide https://about.gitlab.com/handbook/practical-handbook-edits/#remove-trailing-whitespaces
- For git clone, local Hugo server with CLI/Docker, etc. link to this repository and dev guide. https://gitlab.com/gitlab-com/content-sites/handbook#getting-started
Misc
- Update incoming URLs
- From CI/CD linting errors that generate an MR comment with a table to fix. Jamie knows how this is built.
Videos
Note: If doing video recording, screencast mode to show key presses: https://gitlab.com/gitlab-com/marketing/developer-relations/dev-evangelism/de-tmm-meta/-/issues/375#note_1699556581
These videos need to be reviewed and determined whether a new one needs to be made, or leave the old one with a note.
-
Handbook editing: https://www.youtube.com/watch?v=DJo4bQdawSo ; note added that it shows a different repo. Otherwise, it looks mostly the same. May not need a new one? -
Creating new handbook pages and multimedia embedding best-practices -
How to move the location of a handbook page -
Changing a page name and subsequent updates -
Creating mermaid diagrams -
Creating issue templates -
Adding images to the handbook and handbook analytics -
How to add a new directory and page to the handbook -
Trailing whitespace - new, no update needed
Organization
-
https://handbook.gitlab.com/docs/
-
(New) Editing the handbook: WebIDE, for git point to docs?, moving pages, tips troubleshooting pipeline failures | DRI: @cynthia | !2527 (merged) -
(New) Local preview: wrap a page: https://gitlab.com/gitlab-com/content-sites/handbook/-/tree/main | DRI: @jamiemaynard -
Markdown style guide: include reference to linking to other pages | docsy-gitlab!57 (merged) - Tools
-
Shortcodes | Additional content DRI: @jamiemaynard- Including content from another page, such as public hb content in internal hb
- readme from user / project
- redirects
-
-
https://handbook.gitlab.com/handbook/handbook-usage
- Keep guidance on usage
- Remove any “how to edit”, link to it.
-
@cynthia to update | !2278 (merged) -
@jamiemaynard to move to “about the handbook” section ?
- How to update the team page: separate page (keep existing content)
Other action items
-
Review editing team page content -
Update onboarding links: https://gitlab.com/gitlab-com/people-group/people-operations/employment-templates/-/merge_requests/2508
Edited by Cynthia "Arty" Ng