Design documents on GitLab instead Google docs
I really like the idea of spending (some) time proposing a solution before executing it. In that sense I love the idea of design documents that @Finotto introduced recently!
However, I would like to propose a different implementation for it:
Let's use GitLab to work on design documents and publish them in our Handbook!
I think this is better than working on those documents in Google docs. Let me explain why:
- Collaboration - Dog fooding, we strive to use our own product as much as possible.
- Collaboration - Using the Handbook and GitLab is a generally accepted way across the whole company, not only our team
- Efficiency - My daily workflow consists of GitLab only. Google docs adds a second workflow for me, this affects my efficiency negatively.
- Transparency - Publishing design documents on our Handbook is a great way of showing transparently how we design things, helping to attract new people along the way.
- Efficiency - Being able to efficiently and asynchronously collaborate on design documents is core to the way we work.
- Efficiency - Being an engineer, I love using $EDITOR, markdown and git to manage my stuff.
- Efficiency - Using Google docs adds complexity, it's not a boring solution like using what we already use
- Transparency/Efficiency - Documents (and changes to them) don't get lost on Google drive but rather are visible to everybody
I love we "drink our own champagne" and use GitLab for work. I'm really used to short cycles with issues, MRs, comments and TODOs. Being able to review a design proposal in a merge request and comment on it asynchronously is the most efficient way I think we can get those documents done.
Being an asynchronous team, we have to be able to efficiently collaborate on those documents across time zones and asynchronously.
Working on Google docs means everybody needs to adapt to another workflow: Responding to pings on a Google Doc comment, pinging people with email-addresses, not being able to clearly see changes. Simply - it's not as powerful as reviewing a GitLab merge request.
In a recent example, it was much faster to collaborate with Geo engineering team in an issue than dragging the discussion into a Google document.