Documentation Guidelines
For a multi-disciplined team to perform, documentation must be:
- Easy to share with the wider team
- Simple to share with the business
- Familiar and intuitive to contribute to
- Simple to embed into our issue tracker (Jira)
📘 Google Docs: Use for hiring, first drafts, and quick collaboration. Also useful for teams outside of technology.
📔 Atlassian Confluence: Use for dynamic documentation on project work as we work with tickets to flesh out projects and key pieces of work. Share easily with the technology department and key stakeholders. Contextualise documentation and links through from Atlassian Jira. This is our main collaboration tool as a department.
📗 Docusarus: Use to share a static process or implementation with the wider business by sending a direct link. This should be where we can showcase our department. This should mostly be created with a non-tech audience in mind.
Examples are as follows:
| Google Docs | Docusaurus | Confluence | |
|---|---|---|---|
| Hiring Sheets | ☑ | ||
| First Drafts | ☑ | ||
| Mission Statements | ☑ | ||
| Squad Technical Documentation | ☑ | ||
| Product Owner Findings | ☑ | ||
| Overview of a Initiative | ☑ | ||
| Discovery Outcomes | ☑ | ||
| How To | ☑ | ||
| Runbooks | ☑ | ||
| Engineering Processes | ☑ | ||
| Architecture | ☑ | ||
| Checklist | ☑ | ☑ | |
| Onboarding | ☑ | ||
| Ways of Working | ☑ | ||
| Hackathons | ☑ |
Documentation: Spoilt for Choice
At Rapha, we have 3 different areas that we can arguably put documentation:
- Google Docs via Google Worksuite
- Atlassian Confluence
- Docusraurs on rapha.fyi (this very application)
It is openly confusing and ambigious as to where to write and find documentation. Each documentation has a clear cut set of features:
| Google Docs | Docusaurus | Confluence | |
|---|---|---|---|
| User License Needed | Yes | No | Yes |
| Easy to Collaborate | Yes | Yes* | Yes |
| Reviews | No | Yes** | No |
| Version Control | No | Yes | Yes*** |
| Easy to Use | Yes | No | Yes |
| Searchable | Paragraph | Text | Yes |
| Integrations | Yes | No | Yes |
| Instant Publishing | Yes | No | Yes |
| Graphs/Charts | Yes | No | Yes |
| Linked to our issue Tracker | No | No | Yes |
* For those technical members comfortable with git
** Contributions via git require a review - only a few folks have Gitlab able to review
*** Limited version control versus git
Therefore, we took this decision to be able to give us a clear way of working for our documentation.