Let's reorganize the Handbook together!
The GitLab Handbook has grown very large and as a result of its sheer size specific content can be difficult to discover, so it's time for us to take a step back and consider how we can best present content to Handbook readers, both within and beyond GitLab.
Because the Handbook is read and edited by several hundred people and counting and because no one person understands the intent behind every page and every section I think the reorganization process can achieve the best results in the most efficient manner if it is a collaborative, diverse and inclusive, iterative, and transparent process, so let's reorganize the GitLab Handbook in the most GitLab way possible!
To get us started, I'll share some of my thoughts about content organization and reorganization. Dissent and discussion are welcome and encouraged.
- I think the main index (currently the Handbook home page) and URLs should generally arrange content in the most intuitive or otherwise easily discoverable way or ways we can devise, keeping in mind how readers are most likely to seek content. I think that is probably usually by topic or department, but ownerships and associations are not always obvious, so we should have a good think about that.
- Similarly, I think page titles should generally correspond to URLs, but with searching in mind. For example, it's easier to type "handbook/values", so that's good in a URL, but "GitLab Values" is more descriptive for search engine indexers and results.
- I think long pages such as the Sales home page should be separated into several smaller pages—one for every distinct topic.
- Mid-page links are more likely to break and hard to detect when they do break (because missing fragment identifiers don't trigger HTTP error messages), so whenever we use them I think we should take that opportunity to consider whether the linked content is substantial enough to be promoted to its own page.
- Automatically generated fragment identifiers are often longer than necessary and sloppy (e.g., containing sequential hyphens), so I think we should consider what we want them to be whenever we create headings.
- I think user experience should almost always win out over ease of implementation.
I'm sure many people will have interesting and valuable ideas about this undertaking, so please ping anyone you think may be interested in participating, whether in discussion or implementation.
cc @sytses, @cteskey, @rebecca, @clenneville, @mikelewis, @marcel.amirault, @mmcb, @cwilliams3, @jhurewitz, @cciresi, @cynthia, @emilie, @NicoleSchwartz, @dcroft, @brandon_lyon, @toupeira, @jareko, @brendan, @shanerice, @sfwgitlab, @joshlambert, @edjdev, @twbarr, @Emily, @dplanella, @melsmo