On August 1, 2022
Organizations are under pressure to create faster and more innovative software to meet the needs of their employees and customers. This requires a new level of collaboration between developers and business users. However, the traditional model of developers creating software and business users testing it is no longer effective. In the past several years, we’ve seen modern organizations embrace the concept of citizen developers – business users who are empowered to create their own software solutions.
However, citizen developers often struggle with the same issues that traditional developers face: writing effective documentation and general knowledge management. This can lead to frustration and even resentment from business users who feel they are not able to get the full lifetime value from the software their peers create.
In this article, we’ll explore the documentation challenges of citizen development and how to overcome them. We’ll also discuss the role of knowledge management in citizen development and how it can help organizations get the most out of their citizen developers.
Documentation in Citizen Developer Projects
One of the biggest challenges for citizen developers is the lack of experience writing technical documentation. Traditional developers are used to working with detailed specifications and have the clear expectation of writing documentation, but citizen developers often have to “wing it.” This can lead to problems down the road when business users and other citizen developers need to understand how the software works at a deeper level or make changes to it.
To overcome this challenge, organizations need to provide better documentation standards for their citizen developers. This doesn’t necessarily mean more documentation or bureaucracy, but rather quality documentation frameworks and tools that are easy to understand and use. The goal should be to provide enough information to support future maintenance and changes, without overwhelming citizen developers with too much detail.
Knowledge Management – A CD-Friendly Approach
After a citizen developer documents their apps initially, the challenge of knowledge management begins. How can a citizen developer, who has so much on their plate already, be expected to continue documenting their work? This is more so an issue in larger citizen development teams, which is a commonly seen issue in traditional software development projects.
Concept: Documentation Accessibility
It should be easy for other citizen developers, business users, and stakeholders to find and search the app documentation. Consider building an additional app in your existing low-code/no-code tool to house your documentation. This will make it easier for others to find and search for the information they need without having to change systems.
Concept: Documentation Structure
Citizen developers are in a tough position. They need to both document their own technical thoughts for future changes, the proper usage of their apps for day-to-day use by business users, and organizational impact for decision-makers.
There’s a fine line between too much information and too little information. Too much information can make documentation difficult to read and absorb, while too little information can make documentation useless.
Technical documentation is crucial for future maintenance and changes to your apps. If a citizen developer leaves the organization, the remaining citizen developer(s) will need to be able to understand the app and make changes. Other citizen developers may need to learn how to use a new low-code/no-code tool. Technical documentation will help make this process easier.
Technical documentation should include information such as:
- How the app is designed and interconnected
- What actions should be taken to make changes or enhancements
- What processes are in place to test changes
- Who to contact with questions or problems
Citizen developers shouldn’t be expected to create professional-level documentation, but they should be encouraged to document their apps as thoroughly as possible. Larger organizations may wish to utilize a hybrid approach to documentation, where citizen developers create initial documentation that is then reviewed and edited by professional engineers and technical copywriters.
Business documentation is crucial for business users who need to use the app on a daily basis. This documentation should be written in business terms, not technical terms.
This documentation should include information such as:
- How to use the app
- Common troubleshooting steps
- Known limitations of the system
Citizen developers are in a unique position, because in many cases they’ll be utilizing their own app in their day-to-day job. Organizations should take advantage of this and encourage their citizen developers to write business documentation as if they were writing it to themselves. This tactic will result in more natural sounding and easier to follow documentation for other business users.
Organizational documentation is crucial for decision-makers who need to understand the impact of the app or make decisions about future changes. This documentation should be written in business terms and should include information such as:
- What business processes the app supports
- What organizational metrics the app impacts
- What is the expected return on investment (ROI)
- What are the risks and mitigation plans
Organizational documentation is likely to be the most difficult for citizen developers to write and maintain. Depending on the size of the organization and citizen development team, identifying key information such as ROI may involve working with other departments such as accounting or information technology (IT).
Encouraging Knowledge Management
Organizations should consider creating a dedicated knowledge management team or appointing a knowledge management champion. This team or individual should be responsible for proofing the documentation, encouraging citizen developers to document their work, and helping to managing the knowledge gained by using the app.
A knowledge management team or champion can also serve as a de-facto product owner for citizen development projects. This will help to ensure that documentation meets the needs of the business and that changes to the app are made in a controlled manner. They may also help create more engaging content, such as training videos, from written documentation.
It is also important to encourage business users to document their own usage of the apps. Employees can be given incentives to document their processes and the process for doing so should be made as easy as possible. This crowdsourcing method of documentation can help employees learn from each other and helps make long-term documentation maintenance an organization-wide event.
The final step is to make sure that knowledge management is integrated into the organization’s culture. One way to do this is to create a knowledge management policy that outlines the importance of knowledge management and the roles and responsibilities of employees. The policy should be reviewed and updated on a regular basis.
Citizen development is a powerful tool that can help organizations create faster and more innovative software and tooling. However, citizen developers often face challenges when it comes to documentation and knowledge management.
Organizations need to provide better documentation standards for their citizen developers. They also need to encourage knowledge management and at a minimum appoint a knowledge management champion.