Sure, we get that software documentation is crucial for project success, but how do you ensure your docs aren't putting everyone to sleep? PM Kas has some quick tips to spice up your documentation game.
Innerworks is coming soon...
This blog was originally published on our previous Cogworks blog page. The Cogworks Blog is in the process of evolving into Innerworks, our new community-driven tech blog. With Innerworks, we aim to provide a space for collaboration, knowledge-sharing, and connection within the wider tech community. Watch this space for Innerworks updates, but don't worry - you'll still be able to access content from the original Cogworks Blog if you want.
We know what a world might look like without software documentation.
We know it's a valuable part of the project lifecycle that keeps clients and agile agency teams happy, but how do you write it?
Following a recent overhaul of project documentation processes during our company Hackathon, we spoke to Kas, Cogworks PM.
Here's what we learned:
Tips from Cogworks PM, Kas.
1. Keep it short. Agile is all about working well and fast, so there's no need for lengthy, in-depth documentation for the sake of it. Quick, clear, concise sentences will do the trick.
2. Build software documentation into your agile process. We have chosen our monthly company Hackathon as our dedicated time to update our overall company processes as a team. Project-specific updates happen more often, so building software documentation into the project life cycle is a good idea. The first step is understanding the value of software documentation for your team and clients; the second is working out how to document, and the third is where in the agile lifecycle it'll go. If you're an agile team, you should only document your project briefly and often.
3. Create branded templates. For specific client projects, develop a template you can reuse for your next client. A website project will nearly always have a name, project manager, meeting notes, etc.
4. Do demos and peer reviews. Demo your documentation process with the team at different stages to keep you accountable for the documentation due date. Make it fun by sharing an unknown function with another part of your organisation to see if the terminology makes sense.
5. Make it easy to collaborate. Software Documentation is for all parts of a project process, so designers, QAs, developers, strategists, and PMs need to know how to access and collaborate.
6. Secure a winning toolkit. Find a tool for documentation you love (but don't get comfortable with). Building a tool review into your processes is a good idea, as everything has pros and cons. Currently, Miro is our tool of choice for tech diagrams - it's free, highly collaborative and used company-wide, so we're already fans.
7. Use AI to help you structure it. The human touch, personalisation and scrupulous checking from yourself and the team is still needed, but AI can be used as a jumping-off point if you're uncomfortable with writing. GrammarlyGo is still in the early days, but it is already helping can help to simplify complicated thoughts.
To sum up.
When writing software documentation for Agile teams, keep it punchy, practical, and up-to-date.
By collaborating and keeping watch for the best tools, you'll be able to craft documentation that's a real asset to your project, ultimately keeping everyone informed, aligned, and empowered to deliver high-quality working stuff.
Cogworks