| title | description |
|---|---|
Documentation |
How and where to document or share content |
As engineers we operate in many parallel forums: GitHub, Jira, Slack, Google docs, e-mail, Notion, and so on. What content should go where?
When documentation relates to a particular system, leverage in-repository READMEs or doc/s wherever possible.
This includes when the consumers may not exclusively be engineers.
E.g.:
- How to set-up a local development environment
- Definitions of domain models
- API documentation
Other repo-specific interactions such as presenting the rationale for a design or offering code-review should leverage the built-in mechanisms of commit messages, pull requests, and comments.
Project README files should provide enough context to understand and contribute to a project including:
- High-level description of the project's use, as well as metadata including:
- Development stage (development, beta, production, deprecated, retired...)
- Links to hosting environment(s)
- Links to GitHub repo(s)
- Continuous integration and branching information
- Deployment instructions
- Who to contact for guidance
- Any other relevant links
- Instructions for setting up, testing, and contributing to the project
- License (probably MIT) and copyright, if open source
See a recent example 🔒 as a template.
When creating a repo, contributing a doc, or discussing in-progress work, consider whether it's appropriate for this content to be public or private.
Content that should always be private:
- Contact or role details for individuals
- Information about candidates or new hires before they've joined or consented to announce their move
- Production data or logs (including indirectly through migration output, etc.)
- Repositories representing substantial business value, novelty, or criticality (such as the main API, content management system, or auction operator tools)
- Security or compliance topics, including pending security work items or vulnerability-handling procedures
Content that maybe should be private, depending on its sensitivity:
- Incident/support instructions, including data recovery or incident-mitigation procedures
- Internal business rules, definitions, or implementations (tiering, targeting, buyer/bidder qualification, spam heuristics, search ranking algorithms, data partnerships...)
- Un-announced feature work
- User research or industry analysis that may hold competitive value
- References to private content (according to the criteria above) including documentation of private systems, links to private gists that may include private data or logs, etc.
- Code repositories that may not be sensitive themselves, but the discussion of which (pull requests, comments, etc.) has a high risk of exposing product plans, customer details, or private data
This public artsy/README repo is our default location for general engineering content such as:
- onboarding resources
- team procedures and playbooks
- other public resources that are not repo-specific
Notion🔒 is our preferred location for internal documentation, because it is a company-wide default. It includes:
- Documentation and diagrams of internal architecture🔒
- Security bounty program procedures🔒
- Playbooks for handling common on-call incidents🔒
- Any other content that should be private according to the criteria above
Finally, don't forget about artsy.github.io, the engineering blog. Blog posts can be great resources both externally and internally when you've released a new library, solved a technical challenge, refined tooling, or just learned a lesson that might be of interest to other teams like ours.
- engineer-workflow.md
- issues/2 about public vs. private content
- artsy/README
- artsy/potential
- artsy.github.io