...
Documentation should be folded into everything we do like a leatherman.
It should make onboarding as easy as “read our confluence”.
How do we document in a meaningful way that doesn’t kill productivity or piss off frustrate all of the Devs?
There are different approaches to this but it is my humble opinion that documentation should be kept as close to the code base as possible in readme's where generalized, design documentation and educational content should be used at the confluence level. Confluence should then be linked to more up-to-date documentation at the Readme.md level.
...
| Expand | ||
|---|---|---|
| ||
No, Confluence should be educational in nature. It should be high-level and not specific. It can outline general steps and information. Should be used as a way to document new technologies, and initiatives, and be general so as to apply to more than one application where possible. |
Example Readme format
...
| Code Block |
|---|
# APPLICATION NAME
Date Created: 8/14/22
Date Last Modified: 8/14/22
Description:
Tell me what the application does?
Who does it do it for?
How do they benefit?
What makes it special?
Table of Contents:
- [Index item 1](#example1)
- [index item 2](#example2)
...
## Tech stack
- Single page application made in React.js
## Example 1 - Features
## Example 1 - local installation steps
- Do thing 1
- Do thing 2
## Important notes:
> This is a note for new hires
## 🔗 Relevant links
- [link1](https://example.com)
## Runbook
Symptom: "thing happens"
Solution: "Do thing" |
Confluence Format
Fair game! Make it full of pictures, screenshots, gifs. Make it readable. But most importantly, if it could be in a readme because it applies to code, link it one way or the other.GitHub README Template
Confluence guidelines
/rant.