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.
Hello, youve stumbled into the old Cogblog archives
We've switched our blogging focus to our new Innerworks content, where tech community members can share inspiring stories, content, and top tips. Because of this, old Cogworks blogs will soon be deleted from the site, so enjoy it while you can. A few of these might refer to images in the text, but those have been deleted already sorry. Some of these subjects will return, some aren't relevant anymore, and some just don't fit the unbiased community initiative of Innerworks.
If you'd like to take on this subject yourself please submit a new blog!
Farewell Cogworks Blog š
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
Innerworks and Cogworks are proud to partner with Community TechAid who aim to enable sustainable access to technology and skills needed to ensure digital inclusion for all. Any support you can give is hugely appreciated.