diff --git a/source/handbook/marketing/developer-relations/technical-writing/handbook-updates/index.html.md b/source/handbook/marketing/developer-relations/technical-writing/handbook-updates/index.html.md new file mode 100644 index 0000000000000000000000000000000000000000..9370a4db2a2f7f54651db9950dbe597a87bc5cd9 --- /dev/null +++ b/source/handbook/marketing/developer-relations/technical-writing/handbook-updates/index.html.md @@ -0,0 +1,120 @@ +--- +layout: markdown_page +title: "Handbook Updates" +--- + +### Welcome to the Handbook Updates Guidelines! +{:.no_toc} + +---- + +## On this page +{:.no_toc} + +- ToC +{:toc} + +---- + + +To be concluded + +## Why our Handbook is important + +To be included + +Handbook is our rules. How do we wanna play without the rules? + +It's part of the company culture. It's what makes GitLab such a great place to work. + +It's our own reference. It's the way the things are. + +It's the company's documentation. It's where we rely on, it's were we should look for help first. + +It's the answer to our questions. + + +## Continuous Integration + +Small MRs are the best + +We use Continuous Intergration as a feature (GitLab CI), as a culture and a way of developing software. We need to apply the same approach for our handbook. Realease early, realease often. Work in a time-basis operation. One thing at a time. Better something then nothing. + +Better small MRs => be reviewed, approved and merged quickly. This ships faster, and it's easy to revert any bad change. + +Long MRs take too long to get merged. Meanwhile, either you're stucking people to work on the same file as you are, or there will be merge conflicts to get solved. + +Do not submit an MR if you do not have intentions to finish it up quickly. + +Do note take long to merge. + +### Avoiding merge conflicts + +Merge. Pull. Rebase. Lock. + +### WIP + +Work in Progress + +`WIP` before the MRs is useful and valid when your MR is upon review. But do not overuse it. Your work sounds good for you? Remove the WIP and assign the MR to your manager. He or she will add it back if your MR needs a lot of editing. + +The only files you assume nobody will need to change are the ones that don't exist yet; the ones you're creating from scratch. Not the case? So, if you start somehting, make sure to finish asap. + + +## Technical Aspects + +Professional writing techniques and tips => tech writing + +The handbook is technical. Respect the approach, contribute professionally and make sure your tone is kind and clear. + +### Markdown + +Check out our [Markdown Style Guide] for the markup used throughout about.GitLab.com, including any markdown page, handbook page and blog post. You'll +find useful information there, some [Kramdown] magic, and it might save you a lot of typing. + +The markup is important. Respect the standards. + +### Folder Structure + +www-gitlab-com => `/source/handbook/area/subarea/index.html.md` + +images: handbook/marketing + +### HTML Blocks + +- Why +- When +- How +- How to update + +handbook/marketing/ index: + +- modal windows +- purple icons + +=> Bootstraps rows / columns + +=> # of items per row + +=> markdown + html + +### Preview locally + +please preview! please preview, please preview. Oh, and don't forget to preview. + +## Review and Approval + +- Content Review => the Team Member you report to, or someone else assign by him or her +- Markdown and Structural review => tech writers + +Ping someone to review. In case there's no response in one day, ping another person. In doubt? Not working? Got stuck? Any road blocks? Ping your manager. + + + + + +[about.GitLab.com]: https://about.gitlab.com/ +[Markdown Style Guide]: markdown-guide/ +[Professional Writing Techniques]: #professional-writing-techniques +[WIP MR]: http://docs.gitlab.com/ce/workflow/wip_merge_requests.html "Work In Progress Merge Request" +[www-gitlab-com]: https://gitlab.com/gitlab-com/www-gitlab-com/