This is a challenge leading up to the Virtual Contribute 2020 to drive more stage adoption through improving the design of our [docs](https://docs.gitlab.com) and improving their content. Anyone can contribute! This is a truly cross-functional effort among the GitLab team. [Details in Sid's presentation here](https://docs.google.com/presentation/d/1eqaptue2i_0jy0CTbsLZ2eq0j2fMvRnFIQ2VeKd-8dA/edit#slide=id.g83601763a8_9_9). In short: * Improve the site design: make it beautiful! * Improve the content: Highlight not only how features work, but also why they are important and how they have made customers successful. * Supporting work: Automation, ROI calculation, etc. As announced in Sid's [video](https://www.youtube.com/watch?v=EAY-w793PyY&t=409) ahead of the [2020-04-14 General (CEO) Group Conversation](https://docs.google.com/document/d/1zELoftrommhRdnEOAocE6jea6w7KngUDjTUQBlMCNAU/edit#heading=h.1rsm4r66cf4p). Join `#Contribute2020-challenge` to discuss how you can contribute! ## Defined issues See also: [Background information](#background-information), [Further-ideas](#further-ideas), [How to contribute](#how-to-contribute) | Area | Issue | Proposal/Design | Designer/Proposal Author | Implementation Status | Dev/Author | External Links | |---------|---------------------------------------------------------------------------------------------------------------------------------|---------------|-----------|----------------|------------|---------------------| | Content | Edit a feature's doc intro to add the "why" https://gitlab.com/gitlab-org/gitlab/-/issues/215071 | Ready | @mikelewis | | Seeking various contributions/MRs: Anyone can contribute! | | | Content | Add more videos to docs https://gitlab.com/gitlab-org/gitlab/-/issues/215072 | Ready | Various | Complete | Seeking various contributions/MRs: Anyone can contribute! | | | Content | Add user success stories to docs https://gitlab.com/gitlab-org/gitlab/-/issues/214696 | Ready | @mikelewis | | Seeking various contributions/MRs: Anyone can contribute! | | | Design | Restyle home page of docs.gitlab.com https://gitlab.com/gitlab-org/gitlab-docs/-/issues/680 | Ready | @jeldergl | | Needed | [Figma: Docs North ⭐](https://www.figma.com/file/e3QXi7cwhN2TyzoG8IWPMD/Docs-North-%E2%AD%90%EF%B8%8F) | | Design | Restyle header of docs.gitlab.com https://gitlab.com/gitlab-org/gitlab-docs/-/issues/637 | Ready | @jeldergl | In Progress | @nicolasdular | [Figma: Docs North ⭐](https://www.figma.com/file/e3QXi7cwhN2TyzoG8IWPMD/Docs-North-%E2%AD%90%EF%B8%8F) | | Design | Restyle in-page navigation (right-side TOC) of docs.gitlab.com https://gitlab.com/gitlab-org/gitlab-docs/-/issues/666 | Ready | @jeldergl | | Needed | [Figma: Docs North ⭐](https://www.figma.com/file/e3QXi7cwhN2TyzoG8IWPMD/Docs-North-%E2%AD%90%EF%B8%8F) | | Design | Restyle "Help and Feedback" section of docs.gitlab.com https://gitlab.com/gitlab-org/gitlab/-/issues/31206 | Ready | @jeldergl | In Progress | @justin_ho | [Figma: Docs North ⭐](https://www.figma.com/file/e3QXi7cwhN2TyzoG8IWPMD/Docs-North-%E2%AD%90%EF%B8%8F) | | Design | Restyle body content of docs.gitlab.com for better scannability https://gitlab.com/gitlab-org/gitlab/-/issues/31207 | Needed | | | | | | Design | Create a style for a Note-like div for customer stories / testimonials https://gitlab.com/gitlab-org/gitlab/-/issues/215529 | Ready | @jareko | [Ready to merge](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/818) | @jareko | | | Design | Improve the design of the tier badges on headers; clarify .com vs self managed & what you get on click (pricing/trial info CTA) | Issue needed | | | | | ## Background information ### Documentation content * Content guidelines https://docs.gitlab.com/ee/development/documentation/ * Most content is in the `gitlab` repository in the [/doc](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc) path. ### Documentation site * Architecture details https://docs.gitlab.com/ee/development/documentation/site_architecture/index.html * Repository https://gitlab.com/gitlab-org/gitlab-docs/-/tree/master ## How to contribute * **All MRs are welcome - everyone can contribute!** (Or simple additions to the spreadsheets in some of the Content issues.) * **Issues** * If you create an issue or epic for this Challenge, add it to this epic. * If you are looking for ideas, browse this epic and the existing issues labeled ~"Contribute2020-challenge". * Or just start with an MR. * **Discussion** * Discuss ideas and ask for help in [#Contribute2020-challenge](https://gitlab.slack.com/archives/C011S6P9XTM). * For documentation content, the Technical Writing team will be happy to help. (You can also find a technical writer for a given product area [here](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments).) * For documentation site development, UX and the Static Site Editor group (`@gl-static-site-editor`) will be happy to help. * **Labels** * Add `~Contribute2020-challenge` to every MR and issue (if an issue exists)—even if it is a new idea/proposal or an existing issue that might fit in to the Challenge effort. * Keep your MR updated with `~workflow::In dev` and `~workflow::ready for review` * If your work results in further issues or WIP MRs to complete after the challenge, label with `~Contribute2020-challenge-followup` * **Reviews** * For docs content * The Technical Writing team is here to help! After you label your MR with ~"workflow::ready for review", a Technical Writer maintainer will do a high-level style check and help get your content merged as quickly as possible. * For doc site design/functionality * After you label your MR with ~"workflow::ready for review", a UX Designer and engineer from the Static Site Editor group will be happy to review and merge. * When assigned for review, someone from the above teams will move the label to ~"workflow::In review". ## Further ideas Please move items to the table once they have issues/MRs. If you're creating new issues or epics for the challenge, add them to this epic. **Most of these are unclaimed ideas; claim one, or add your own!** See also: Sid's presentation in the intro above. - **Content** - Improve content on a page for a feature you are familiar with. You can find a link to a feature's doc via the [about.gitlab.com Features page](https://about.gitlab.com/features/) or by browsing https://docs.gitlab.com. - Add meaningful introductory content about a feature to better summarize what it can do and why you'd want to use it. Add context like who would use it, in what context, with what goal. - Add cross-links to complementary features from other stages, perhaps as part of a use case that spans stages. Or at least across categories/features, to drive adoption. - Add stories of real user/customer success with a feature (perhaps omitting customer names unless you have their permission) https://gitlab.com/gitlab-org/gitlab/-/issues/214696 - Add mentions of how GitLab itself uses features, e.g. https://gitlab.com/groups/gitlab-org/-/epics/947#note_325936917 - Images - Add new or better screenshots - Create illustrations and diagrams - Multimedia - Create a new video summarizing a feature or showing how to use it and add to its relevant documentation page - Identify existing videos to add to their relevant documentation pages. Sources might include GitLab's main YouTube account, Unfiltered, the Release Post, etc. - Add troubleshooting information to a Troubleshooting subsection on a given page, perhaps brought in from the GitLab forum or a Support case. - **Design** - Upgrade our landing pages to offer more clarity on the available features like https://stripe.com/docs - **Data/Automation** - Automate the inclusion of a link to the latest GitLab release post on the docs.gitlab.com landing page (in a way that works with @jeldergl's new design in https://gitlab.com/groups/gitlab-org/-/epics/1808). - Determine if there is a way to pull information directly from [features.yml](https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/features.yml) despite being part of a different project than the docs. - Is there a way to determine any ROI e.g. via clicks from docs that lead to customer acquisitions or upgrades? - Content metadata - Create a format for adding frontmatter to all doc pages identifying the page's relationship to a Stage/Section/Category/Feature - Develop a way to reflect this data in Google Analytics - Do an analysis of how many pages link to content from another stage ## Deadline To be included, content needs to be merged by Thursday, April 23. ## Results All ~"Contribute2020-challenge" MRs [merged](https://gitlab.com/groups/gitlab-org/-/merge_requests?scope=all&utf8=%E2%9C%93&state=merged&label_name[]=Contribute2020-challenge) vs. [still open](https://gitlab.com/groups/gitlab-org/-/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=Contribute2020-challenge) ### Examples * Key Example: **Code Quality** * URL https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html * Includes: * Video added * Customer story added (Currently in a note, but we'll be trying a new style after Contribute) * Encouragement of cross-feature adoption * New site header (purple, matching GitLab application) * Newly styled Help & Feedback section at the bottom * **Content examples** * Including the "why" * Push rules: Why blocking secret file push is important ([live doc](https://docs.gitlab.com/ee/push_rules/push_rules.html#prevent-pushing-secrets-to-the-repository) / [diff](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30241/diffs)) * Videos included in docs * Feature flags: Add video showing use with Sentry Error Tracking ([live doc](https://docs.gitlab.com/ee/user/project/operations/feature_flags.html) / [diff](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30203/diffs)) * Building images with kaniko and GitLab CI/CD: Video walkthrough of working example ([live doc](https://docs.gitlab.com/ee/ci/docker/using_kaniko.html) / [diff](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30004/diffs)) * Other MRs open and many more vetted for inclusion per https://gitlab.com/gitlab-com/marketing/digital-marketing-programs/-/issues/2728 * User success stories included in docs * (Still in progress https://gitlab.com/gitlab-org/gitlab/-/issues/214696; Cases from https://about.gitlab.com/customers/ to be mentioned/linked from docs shortly.) * **Design examples** * [New designs for docs.gitlab home page, left nav, TOC (right nav), header (top nav), and Help/Feedback section!](https://www.figma.com/file/e3QXi7cwhN2TyzoG8IWPMD/Docs-North-%E2%AD%90%EF%B8%8F?node-id=0%3A1) * New header (top nav) ([MR](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/813) / [review app](http://nicolasdular-header-redesign.178.62.207.141.nip.io/ee/README.html)) * New Help & Feedback section (bottom of each page) ([screenshot from live page](/uploads/88a05b84176c60dd3029e923b780317d/Screen_Shot_2020-04-22_at_10.20.39_PM.png) / [merged MR](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests/804)) * Following the request to make docs _Stripe-beautiful_, Tech Writing and UX actually met with a Stripe tech writer we know! * [Notes](https://docs.google.com/document/d/1GHk-t4Oo45gdE9bn8uFDaCvaxiI5JraGemIntzgTX6w/edit) * In alignment with their heavy use of user research, we did internal research in choosing among left-nav icon sets for the Challenge; otherwise, their team has had some similar challenges, some things they've done better, and some areas where GitLab has an advantage (e.g. no need to build the app in order to build the docs); we came away with some takeaways for future consideration\> * **Data examples** * Implemented new [tracking of YouTube views in Google Analytics](https://analytics.google.com/analytics/web/#/report/content-event-events/a37019925w65271535p67064032/_u.date00=20200422&_u.date01=20200422&explorer-table.plotKeys=%5B%5D&_r.drilldown=analytics.eventCategory:YouTube/). ## Thanks! * Amazing new site designs: @jeldergl * Dev work to implement/review designs: @nicolasdular * The most content MRs (5x)! @brendan @DarwinJS * Content MRs: @sselhorn @rdickenson @justin_ho @dnsmichi @justinfarris @trizzi @cynthia @mjwood @abuango @jrandazzo @jheimbuck_gl @johncoghlan @ebrinkman @mikelewis @msedlakjakubowski @aqualls @clenneville @weimeng * Facilitating and planning: @mikelewis @cnorris @shanerice @markglenfletcher @godfat @susantacker @marcia @pritianka * Further design work: @jareko * Reviewing: The Technical Writing team