I read this article reposted on dev.to, and it resonated with me.
Much of that's because the project I'm currently working on has a lot of parts that are actively changing. We're using an agile approach, and I need to keep the other devs on the team up-to-date with the latest information. Additionally I need to make sure QA understands how the various pieces are supposed to work. If they didn't, how would they know when something wasn't working correctly?
My fix for the issue was to start a collaborative design document where we outline the necessary details for each piece of the site. That way we don't lose track of the small decisions or the latest updates when parts of the site need to change.
Along with this, I've started framing every question from QA as a bug. If they ask why something doesn't match the docs, either the functionality is wrong, or the docs are wrong. With complex features, they may ask for additional details. If they had to ask, the docs didn't explain it well enough, and the fix is to work with QA to get enough of the clarifying details written down.
This has also helped with onboarding new developers onto the team. In the past, most projects I've been on were with a sink-or-swim mentality where the devs on the team are just expected to keep up with the changes, while not necessarily being aware of other features. This often led to duplicate effort, rework, and bad integrations where pieces that were supposed to work together didn't.
Leading by example with the design doc has helped as well, as the other devs can feel empowered to update the docs when they find issues. It helps to show that there's no expectation for the docs to be perfect, so they can feel comfortable writing in their own way.
And probably most importantly, I set up our docs as a 70-line node build to generate what amounts to a flat-file CMS using markdown files. The simplicity of the system, while limiting in some ways, is advantageous in that it's very easy to write without wasting time on formatting, publishing, or any other non-writing-of-documentation things that plague other systems.
The workflow for editing is:
- open a text file in your editor of choice
- write
- save
- commit
I hope to eventually write up a longer post going into more detail about how I have everything set up. It'd also be nice to make some more improvements on the docs builder.
So far it's worked out pretty well, and it's validating to see that I'm not the only one thinking this way.
