What is software documentation, and what are the types?
Software Documentation is the ultimate guide for everyone that comes into contact with a piece of software.
There are lots of different types of documentation in a digital project, but they can break down into two categories; product documentation and process documentation. Both types explain everything a specific audience needs to know about a product to use it as intended and have a great time doing so!
- System Documentation is aimed at technical professionals who intend to improve, extend or understand a product. This type of documentation agencies and clients care about as it includes technical information about website architecture, UX, code structure, etc.
- End-user documentation is for a product's intended use (in a website project, end users are content editors or browsers to a site). This type of documentation is non-technical and easy to digest, so the user experience is always good.
- System admin documentation. This type of documentation is for system admins and IT professionals to configure, operate and maintain a computer system or network.
- Process documentation is the "how" of product documentation. The development, design and strategy process goes into making a product and may include plans, reports, estimates, schedules, etc.
Why don't people like documenting stuff?
The truth is documentation is an aspect of development that is often overlooked. A quick search of "software documentation" returns a string of results like: "The importance of software documentation" or "why insufficient documentation can create problems for developers."
So why is it overlooked? Here are a few of the common reasons:
- It's a laborious and pricey task. This is especially true in waterfall-style development projects as the documentation is often required up-front, a long day at the office for anyone.
- It's not a priority. Sometimes documentation needs to be built into the project lifecycle and may be treated with a different weight than testing or deployment.
- Teams need to learn how to write it. There's no clear template, so teams stare at a blank page for ages.
Lack of toolkit. It can be hard to get anywhere when software documentation tools are clunky and not user-friendly.
- Out of sight, out of mind. In some development teams, technical documentation may be absent if developers aren’t aware of user feedback. Without feedback, developers may assume that everything is working as it should, making them less likely to address common user questions or concerns in the documentation.
Does documentation create happier clients and teams?
We think so.
We're thankful for the excellent documentation provided with open-source CMS, Umbraco, including detailed technical documentation and extensive release notes with every update. For decades, the CMS's thriving open-source ecosystem has encouraged collaboration in every project area, with no shortage of technical partnerships, community festivals and quality documentation.
We've been contributing to Umbraco since 2008. In our time, we’ve built a few Umbraco packages that have earned us a few shiny badges, like the Umbraco Contibuting partner award and individual awards known as MVPs.
So, as package builders and meet-up leaders, we want the community to question and improve our documentation the same way other creators wish us to improve theirs; that's what makes the end-user experience for our clients so good. Read more about What it means to be a Umbraco Gold Partner.
Plus, documentation isn't so terrifying when you're an agile team.
Although each project is different, it makes business sense for us and for our clients to be able to reuse parts that worked from one project and transfer them to another. Moving with agility is made possible with process documentation about the standardised ways we do things in code, design and project management.
As our processes change, so does our process documentation (in small manageable increments), resulting in a collaborative company handbook packed with guides on projects and cogworks-specific processes so the team can dip in and find the most efficient way of doing stuff.
Why documentation makes for happier clients and agency teams at Cogworks.
- Transparency. Good technical documentation helps to create transparency in the development process so we can understand what is being worked on, what has been done, and what needs to be done! Sharing process and project documentation with clients also helps build trust; who doesn't want a more positive working environment?
- Communication. Project documentation helps us quickly hand over client projects within our and clients' teams! This document, as well as top-tier communication, makes light work of understanding the details, focusing communication on the future rather than trying to understand the past.
- Agility. Good technical documentation does wonders for code quality which keeps our teams and clients happy through regular documentation of code and code reviews. Great client relationships are forged on many things in a digital project; one is logical and quality implementations that help to adapt their technology to compete in a fast-paced industry.
- Stronger teams. A handbook to a project or process helps new teammates quickly get into the swing of the Cogworks way, allowing new employees to spend more time doing what they love and less time wondering what to do next.