Contributing to the Handbook Product or Website
There are many facets to the Handbook. Some benefit greatly from distributed ownership, while others can benefit from unified vision and principles. As Sourcegraph continues to grow, and if we want to remain handbook-first, we want to make decisions for the Handbook that allow us to scale.
The purpose of this page is to define these facets, their ownership, and how to contribute to each. Ownership in this context means the person or group primarily responsible for driving improvements, owners are not the only contributors. The contribution sections below describe how (and by whom) these types of changes are made. These will change as the Handbook team grows, and the product evolves.
The Handbook is part of the Content Platform team strategy.
Handbook Facets
Content
Definition: The actual written content in the Handbook, mostly stored in markdown files
Owner: Every Sourcegraph teammate
Contributions: See how to contribute to the Handbook here. As Sourcegraph teammates, we share responsibility for keeping the handbook accurate and up-to-date.
Content Structure/Guidelines
Definition: Best practices for easy to read+follow content that creates internal consistently & maximizes usability
Owner: Handbook Team
Contributions: Content best practices are detailed here and updated by the Handbook team with contributions from the Sourcegraph team. Propose changes to that page in a PR, or raise in the #handbook channel.
Information Architecture
Definition: How the Handbook’s content is organized
Owner: Handbook Team
Contributions: The Information Architecture is maintained by the Handbook team, but also by all Sourcegraph teammates each time you add a new page. If you have a question about where a new page should go within our Information Architecture, ask in the #handbook channel.
Product Design
Definition: How the handbook looks, feels, and is interacted with. Best practices for usability, readability, and accessibility.
Owner: Handbook Team
Contributions: The Handbook team does not currently have a designer, but collaborates with product design when possible to make decisions about Handbook feature changes. Raise any questions, feedback or concerns in the #handbook channel
Publishing Process
Definition: The process for writing and publishing content including Handbook checks, review process, and editing tools.
Owner: Handbook Team
Contributions: The Handbook team aggregates feedback on the Handbook publishing process and logs issues in Github. Work on these issues occur as part of the Content Platform team strategy. Raise any questions, feedback or concerns in the #handbook channel.
Product Engineering & Deployment
Definition: The technical foundation for the Handbook & how technical changes are made
Owner: Handbook Team
Contributions: The Handbook team aggregates feedback on the technical foundation of the Handbook and logs issues in Github. Work on these issues may occur ad hoc during Handbook Hacking Hours or as part of the Content Platform team strategy. Raise any questions, feedback or concerns in the #handbook channel.