As part of software development I have used tools that are helpful during the development process. Two of these tools are version and issue management tools. These tools are used in software development for organization and monitoring status of the software development. While they are associated with software development, I have found them useful for other types of projects such as technical manual development. I’ve successfully used version management for technical manuals development for fifteen years and issue tracking for five years.
In this article I provide an explanation of what version management and issue tracking are and why they are useful for projects developing electronic content or data. I then provide a list of assumptions of why these tools are hard to implement for other types of projects. Finally I explain ways these assumptions aren’t always correct and why a small team in a small company can use these tools in their process.
Version Management and Issue Tracking
First, a short explanation of what version management and issue tracking are.
• Version Management – The methods used to store and track changes to files as they are changed. A simple version management system is creating folders with different dates for different changes to the files. Or naming the files with a number and/or date to track changes. There are software tools that are used to automate this process and store the files in a database. These tools store the original files and track changes to the files on a central server. Multiple people access the server and obtain copies of a version of the files. A copy of the most recent changes or older versions can be checked out, with all files that are associated with that specific version of the files. Logs are kept of the changes, including the user who made the change and any comments they added about their changes. The objective is to have the ability to recreate a file or set of files reliably on system where the files were not created. A user has the ability to reliably check out a version from a specified date or release and have confidence that the files released at that time match the marked files on the version management server.
• Issue Tracking – A process of tracking problems that occur for a product or project. The problems are assigned to a person or group and are tracked to resolution of the problem. The resolution may be a fix for the problem, a workaround or a schedule for a planned fix in the future. In some cases the issue may be marked as working as designed and no changes are made. Issues are assigned a priority based on their impact to the product or project. For example, a priority one issue is something that prevents use while a priority 5 issue is does not occur often or for very many users. Issues with a priority of 1 are worked on first, priority 5 issues may not be addressed for the current revision. A simple method of issue tracking could be a list in a notebook. Software developers use issue tracking software so issues can easily be shared with a team to monitor progress. The objective is to monitor issues to make sure they are closed or workarounds documented if they cannot be fixed.
Version management and issue tracking are general concepts that are useful during software development . As a result there are software tools that are used to automate part of the processes. These concepts are often used in other types of projects but specific software tools aren’t always used. As I mentioned, people use folders and lists to track versions and issues. Using my experience in software development I have used version and issue management software in technical manual development. There is some additional setup work at the startup however the tools save enough time during the project that the start up work pays for itself during development.
Before using version management software, our team used a shared file server with a folder structure to manage files. During that time I observed the following problems.
• Files missing right before deliveries
• Lost changes in files
• Confusion about the latest version and changes in the files
• Uncertainty of who had made changes and who should work on a file
When I was part of a startup with this same team I insisted on the use of version management for the files. At first there was grumbling about learning the new tool and it was hard to understand. Within six months everyone supported the version management software because of the following benefits.
• Ability to restore a file easily when changes caused problems
• Reliable set of the latest files for deliveries
• Ability to view who had made changes to a file
• Better communication and assignment of responsibilities for changes
Later on I setup issue management software for tracking the status of changes made to the files. Before setting up issue management we had several problems, as listed below.
• Multiple people working on the same file at the same time
• Uncertainty about the status of files
• Uncertainty of who was responsible for the current stage of the file
• Out of date tracking of added and deleted files
After setting up and using issue management software we noticed improvements in the following areas
• Fewer problems with people making changes to the same file at the same time as another person
• A dashboard displaying the status of the file set and what files were ready for deliveries
• Up to date information about who was responsible for modifying files or editing them
• Up to date information on all of the files to be included in a revision for a delivery
While the deployment of a version management and issue tracking may require some help from an IT person, the usage of the tools are relatively simple. In the next section I want to address the assumptions project leaders may make about implementing these tools for non-software related projects.
Here are some of the assumptions I have heard about not using tools in non-software related projects.
• Hard to deploy – There are some steps to take when choosing and deploying version management and issue tracking software. And in larger organizations the deployment does require IT support so the software is evaluated for a fit within the organization. These issues can be challenging to overcome for a project, especially if the company IT system is very rigid in what it allows on the network. Due to these challenges it takes too long to setup and use tools so it isn’t worth using them.
• Too expensive – There are many different version management and issue management software tools and some of them have a license costs that might be prohibitive for smaller teams or companies.
• Hard to use – Some of the version management and issue management software have complicated interfaces that require training to use. There may be extensive training for the administration and maintenance of the software and additional training for the users. In addition, some of the software tools may require planning for the assignment of roles and responsibilities for larger teams.
• Doesn’t provide enough gain for projects – For small projects the cost of software licenses, IT support, training costs and slow progress on new projects may not be overcome by the long term gains of version management and issue management software. As a result, companies are not willing to pay for the deployment of these tools for their teams.
The summary is that the deployment of the tools for small teams doesn’t justify the required expense of using tools for non-software projects. In the next section I’ll address these assumptions based on sixteen years of experience using tools in a very small company with small budgets.
As a small business owner that develops technical manuals with an interest in keeping expenses low, quality high and meeting deadlines, I am very interested in appropriate software tools the support those goals. What I have found is that version and issue management software can be bought and used in ways that keeps costs low, improve quality and support meeting deadlines.
Version management is useful when deployed at the appropriate level. I will say that we use version management for projects that may have only one person working on them full time and we still see benefit.* Here is what can happen after you implement version management
• Known collection of files – When using version management you have identified and stored your key files required for deliveries. When using a file server, the files may exist in multiple directories for multiple users.
• Consistent set of references in files – The files are setup and organized in the same way on every technical writer’s computer. This means that every writer will have access to the same set of files in the same directory structure. This eliminates finding missing files that are stored in different locations on a network.
• Ability for users to get old versions of files themselves – There are times when it is useful to get an older version of a file to correct problems. If the files are on a file server, the user has to contact IT to get an older copy of the file. This can take time as they try to find a suitable version. In addition, a backup doesn’t store all versions of a file that occurred in a day, it only stores one copy. The old version may be from the same day.**
• Ability to recreate a file set used in a specific delivery – Version management software supports marking a set of files with a tag. When getting a copy of files, the tag can be used to specify an alternate set of files. If a tag is not used, the latest version of all files are checked out. A tagged version is useful when trying to recreate issues that are found after deliveries
• Use of a local file set that doesn’t interfere with other’s work – With the version management systems I’ve used a local copy of the main set of files is copies to my machine. I can work with those files without interfering with others work. If I break something, it does not break it on other machines.
Issue management is useful for any project. The difference is the method used to log issues. For small projects, 1-2 people with few deliverables, an Excel sheet might be enough. For larger projects, an issue tracking system is more useful. When tracking issues, here are the benefits.
• Documented issues – Many times people rely on memory to track issues. This means that issues might not be addressed if the person doesn’t remember them. Documenting them makes sure issues are tracked to closure of some kind
• Quick status of projects – With good summaries of the status and priority of issues, it can be easy to get a sense of how the project is going. If there are 100 issues, with a high priority and open status, that can indicate there is a lot left to do or fix. If there are 50 issues but most of them are closed or of low priority, the project is probably close to finish. If the 100 high priority, open issues are seen in the week or two before a delivery, the delivery is probably going to be late. When the project is monitored at least weekly, this status can be used to redirect people focus or communicate with management that extra help might be needed to complete the project on time, at the appropriate level of quality and within the budget.
• Documentation of responsibility for files – An issue tracking is used to assign people to work on certain files. This provides a snapshot of who is working on what an allows management to review and reassign to meet deadlines.
If version and issue management seem right, I recommend the software tool Subversion, called SVN, for version management. There are many implementations that support this software tool. We use a Windows based server, with GUI dashboard, called VisualSVN. A file repository and users are defined on the server. Permissions can be set to limit access to different repositories.
An SVN client is used to access the files on the server. We use TortoiseSVN which is integrated with the File Explorer on Windows. This means that users can right click to check out and update files. The client displays a status symbol next to each file that indicates if the file is unchanged or if there are changes that should be committed to the server. A quick glance shows what is changed, deleted or added.
It is easy to use for people who are not comfortable with tech tools. I have worked with technical writers with varying levels of expertise in using software tools. All of them have used this tool and gotten comfortable with the concepts of updating and committing files. While SVN implementations are based on Open Source, the software tools have been in use for many years and are considered acceptable for us by IT organizations I’ve worked with.
For Issue management, I am using a tool I found that supports a web interface and a desktop client. The software is called WebIssues. However, this is a newer Open Source project that may not be as acceptable to IT organizations. There are many other issue tracking systems, your organization may already be using one. There are many web based versions that can be deployed. I like WebIssues because it can be customized and it has a desktop client that seems to be easier for writers to work with. Basically, it reduces the friction involved in looking at issues in a web browser.
With a desktop client, double click, login, start using with minimal wait from the server. With a web based system, start a browser, browse and find the Issue tracking website/URL, login while waiting for the server to respond. When adding time to the startup, users can get frustrated even if the added time is only a few seconds. A web interface, at this time, is usually not as flexible as a desktop client so that can add to the frustration. I am now looking at issue tracking in MS Teams and the possibility of setting up and using the app in the MS Teams software. When possible I use mainstream tools to increase the likelihood of IT support for them.
Here are some best practices for version management
• Update your file set often. Commit changes often. – It can be distracting to update your local file set but it makes sure you stay up to date with changes others are making. It’s also important to commit your changes often. When you get something working or you’ve added new content, commit your changes to the server. Committing your files puts a copy on the server so others have access to it.
• Communicate with others on what you are working on – The largest problem with version management is a lack of communication between team members. If you choose to work on files that others are working on, your changes may interfere with the work they are doing. Version management does not replace the need for communication
• Assign sections of the file set to members of the team – To avoid problems it can help to assign certain parts of the file set to specific people on the team. For example, we develop operator and maintainer technical manuals. We usually assign a person to work on the maintainer manual and another on the operator. When they work on files they don’t interfere with each other. They do need to communicate because there are sections of each manual that are duplicated such as the general information for the equipment.
Here are some best practices for issue management
• Daily review of issues by a team lead – There should be a lead who is reviewing issues on a daily basis. This can help to identify large problems early enough so they don’t impact schedule, budget or quality
• Communication about issues – Logging an issue should not assume that the lead or other team members know about the issue or that they may need to fix something. There should be a chain of communication to make sure issues are assigned and corrected in a timely manner.
Version and issue management software are useful tools even for small teams. They provide a foundation for managing project files required to generate a product for delivery. They are only tools and do not replace leadership, management and communication for a project. When used appropriately they can supplement management of resources, people and objects, and provide documentation that is useful for communication about the project. I have helped other companies implement these tools and I’ve received feedback that they have helped them manage their files and improve the quality of the product while staying within budget and delivering on time. They had problems using other methods and ended up using tools like this for their development of technical manuals.
While version and issue management software is not a fit for all projects and teams, they do have value for small teams that might not have considered them. Based on our experience, the use of version and issue management tools have saved us time and helped improve the quality of the manuals we deliver.
* Note: Our company also has a person who is comfortable with the software and can troubleshoot and fix common problems that come up when using the software. Not every company has this kind of resource and may not feel the learning curve justifies the long term benefits. We also deal with a lot files, 100’s to 1,000’s per project, and version management software helps us manage those files. For people dealing with smaller sets of files, version management is less of an issue. I would recommend use of version management if your project needs to manage file sets that are in the hundreds.
**I do know that cloud servers are implementing versioning of files so people can restore copies. This is not version management, it is a simpler method of restoring backups. From what I’ve seen, the number of old copies is limited in order to save space in the cloud storage. For small projects with a small set of files, this versioning may be enough to support their version management needs.
Pictures by J.T. Harpster, prints of selected photos can be found at our Redbubble shop
Help support our work on Patreon, get access to short stories and news about Shell Creek Publishing.
Sun, 02/05/2023 – 20:57