Tag: planning

  • Documentation and Reproducible Builds – Critical Pieces Software Solutions

    Documentation and Reproducible Builds – Critical Pieces Software Solutions

    One of the things I see most often plague an organization is the lack of documentation and reproducible builds. That has not been historically an issue. However, when the downsizing and rightsizing of the turn of the century kicked in, many developers moved on or were let go. While those were not bad business decisions, they did allow some critical knowledge to walk out the door. I have come across several organizations post the COVID lockdown that took too many years away from maintaining their systems. They have paid the price for a lack of documentation and reproducible builds. These are two things that are often viewed as academic but are actually critical to the longevity of a solution.

    Why Bother With Documentation And Reproducible Builds?

    If there is a winner for the most common rookie mistake in software development, then this pair most likely tie. I cannot count how often a young software shop changed code on production systems to “save time” or skipped documentation because the code was “easy to read” or intuitive. While there are arguments for these measures, they miss out on the long-term value of a short-term fix. Even worse, an application is useless if we can’t build and deploy it. Those steps almost always require both documentation and reproducible builds.

    There are some very smart technical people in the world. However, even the smartest can look at a solution and be completely perplexed. There are so many moving parts in most modern solutions it can take days or weeks to get an idea of what is used to create a solution. We need documentation, at least, to help us get an idea of what a solution is made of and the mindset of the developers. This is even more essential to taking over a solution that was written with technology that is no longer viable.

    The Skip A Version Approach

    In the early days of software development, there were many companies that embraced the skip-a-version approach to upgrades. This smart compromise kept the company current without getting stuck in an endless upgrade cycle. It was easy to get into a rut where upgrades came so fast it felt like you were always learning a new system. That frequency often eliminated productivity gains and frustrated users. We still can see this challenge occur when software is updated “too often” and users are just getting comfortable with a version when an update comes out. That is why some people turn off automatic software updates and seem far more productive than those on the leading edge.

    While a version or two can be a smart decision, software often changes dramatically over a few versions. There also is a challenge of getting old versions that become more of an issue as software ages out of use. Sometimes, releases like Windows XP stick around for several years. However, that is the outlier and not the norm. Software can be almost unobtainable a few years after release in some cases. That can make it almost impossible to build or update that custom solution you paid so much to build a few years ago.

    Provide A Regular Check-In

    Disaster recovery plans critical tools like fire extinguishers should be tested periodically. When you fail to ensure they are current you leave yourself open to experiencing them failing at the worst time. Software and technical solutions are very similar to this. You need to periodically ensure they are current enough to be ahead of disappearing technology. Operating systems are a very common example of this. Your application may run fine on a specific operating system. However, that OS will age and eventually become unsupported. That alone is a reason to upgrade your system. Even worse, there are things that can happen that make OS sunsetting look like a walk in the park.

    Many solutions are created on a language or framework that has specific version requirements. As the language and frameworks age they may or may not be as compatible. Your solution may require some libraries to be updated. On the other hand, the libraries required may no longer be available. Technologies fade and die. That can put you in a situation where your current application no longer works and you have no way forward other than creating it from scratch.

    I have come across more than a few examples of this. In some cases, the original documentation and source code was lost. That caused the company to have to re-imagine the solution based on how they remembered it working. If that sounds difficult then you are correct. It is better to forget the old solution existed in that case as you end up second guessing every feature and how it needs to be implemented.

    How Did I Do That?

    Have you ever looked back at a task from months or years ago and asked yourself how you did it? The forgotten aspects may be a critical step or piece of information. This problem is why we take notes. We want a way to remind ourself of what we did and how we did it. Documentation and reproducible builds provide a way to take detailed notes for a developer to use in learning how another developer got the job done. The end product is almost never enough. There are hidden details in the code and even the build process. Deciphering these details can cost even a seasoned developer weeks of trial and error. Sometimes the original approach is lost just like dead languages or other bits of knowledge that can not be recovered.

    Next Steps

    Now that you are sufficiently warned, you are asking yourself what you can do to ensure that documentation and reproducible builds have been adequately created or provided for. The simplest solution is to ask for them from your developer or team. They will either explain why those do not exist or point you to their answer. For the non-technical among us, there are a few questions you can ask to help vet the documentation and build process without learning the system inside and out.

    • Ask how someone can access the source code. You might even request a copy to store somewhere safe.
    • Look for a list of logins, passwords, and server details. These should include ways to access the server as well.
    • Verify there are steps to build the solution documented somewhere. You might even attempt them or hire a third party to do so.
    • Request the developer or team to do a “clean install” or build. Things can be forgotten so forcing the developers to build the solution on another machine can highlight the gaps.
    • Ensure a list of technical details are provided. This includes languages used, version numbers, libraries, frameworks, etc. These can be critical to staying legal and avoiding surprise license issues or costs.

    About RB Consulting

    Feel free to schedule a time to discuss your next project with us and see if we might be the perfect partner for you. We take these relationships seriously and are happy to point you in the right direction if we are not a good fit. Years of being on both sides of these relationships have taught us a lot. That initial call is free, and there are no obligations. You have nothing to lose. 

    Our experience has taught us a lot about the pitfalls and challenges of custom software. Likewise, we have an e-book that can help you explore all the steps in building software, including a few templates. However, we ask that you share an e-mail address so we can send you a copy. We will add you to our monthly newsletter, but you can unsubscribe anytime. Your data is not shared with anyone else. Learn more about our book here.

  • Clickable Demos And Wireframes

    Clickable Demos And Wireframes

    Creating software requires using tools like clickable demos and wireframes to bring a vision to life. Likewise, these tools provide a canvas upon which to refine that vision. There are many ways to make the most of these tools. Thus, we will start with a definition and then move on to how to make them work for you as a developer or a customer.

    Clickable Demos and Wireframes Defined

    These two ways to build and demonstrate software are so common it feels almost unnecessary to define them. However, we must be clear on how these tools work so we can make the most of the efforts involved. Along with effort, time is invested in these approaches, and we want them to be used as efficiently as possible. First, a wireframe is a drawing of some form or page of an application. It gives a sense of look-and-feel as well as user experience. A series of wireframes can be used to walk through a user story, much like a child’s picture book.

    Next, we have a clickable demo. This is sort of the next evolution of a wireframe. In this case, we have forms and pages that are “live” enough to click on buttons or links and navigate through to another page. The most significant difference is that wireframes tend to be more UX-focused, while the clickable demo is more about displaying flows and actions. Think of them as form (wireframes) and function (clickable demo).

    Using Them For Better Communication

    We start with the most critical outcome of these tools. They provide a way to communicate the application being built amongst technical and non-technical team members. We get to see what it will look like or at least closer to it than words on a page. Even drawn images will differ from how they look on a computer screen. These tools take us through the process of building the interface (and potentially navigation) and then provide a way to share it with others. Better yet, we end up with something people can refer to for edits and additions that are more concrete than a few sentences in a document. Those pictures are worth at least a thousand words.

    Try Before You Buy

    One effect of using clickable demos and wireframes is that users see the result in action. While it is imperfect because performance and similar issues can arise, it still shows details a vision does not. I am amazed at how often these tools lead to minor or even drastic changes to the user experience or features available. The users get a form of “try before you buy” in that they can see it working to some extent. In any case, a greater degree than a document shows.

    User Error and Developer Assumptions

    The testing portion of application development can also take a long time. There are user errors that were never conceived and developer assumptions that show up only once the solution is in use. Even regular product demonstrations can suffer from these afflictions as demos tend to be scripted and controlled. It is not the same as putting it in the hands of users. That is where a clickable demo can provide a ton of value. A user can be asked to “drive” a demo or be allowed to use it on their own time. I highly recommend this as part of any clickable demo strategy. Set it up so users can spend time with it and click around to assess it. You will be amazed by what they uncover and the feedback they provide.

    Follow The Rabbit Trails

    Happy path testing is the name for testing a system using pristine data and flawless navigation. This has its value but doesn’t do much to uncover bugs. The best testing comes when users try a different approach. Use this to your advantage while showing off a wireframe or clickable demo. You can ask several questions during the demo to chase down those details and potential bugs.

    • Is there anything missing from this process?
    • How quickly do you expect this action to respond?
    • If this action fails, how would you expect to be notified?
    • What are some ways you can see this action failing?
    • Does this make sense, or would you prefer a different path to trigger the action?
    • Is this an action someone in the room typically does? Or do we need to contact another person to serve as a subject matter expert?
    • Look closely at the data on the screen. Does it provide what you need to perform your job?

    Craft The Story

    While there are many good ways to use these tools, the best is to make your user stories come alive. These present a solution far better than even the prettiest and most detailed user stories. There is nothing wrong with them. It is just that visual examples remove a lot of ambiguity while clarifying communication. Make them a part of validating user stories and designing them in partnership with customers and users. The user stories almost become the script you walk through using the wireframes and clickable demos. If they do not match up or users get confused, you know you have changes to make.

    Next Steps

    Feel free to schedule a time to discuss your next project with us. Every project we work on includes demos and similar discussions regularly. We build clickable demos and use wireframes as applicable to ensure the team has the best tools for discussing the solution and vision. Likewise, those include a release our customers can use to test the features further and get comfortable with the solution. We are happy to help you with investing in requirements and improving the overall success rate of software projects. 

    Our experience has taught us a lot about the pitfalls and challenges of custom software. Likewise, we have an e-book that can help you explore all the steps in building software, including a few templates. However, we ask that you share an e-mail address so we can send you a copy. We will add you to our monthly newsletter, but you can unsubscribe anytime. Your data is not shared with anyone else. Learn more about our book here.

  • Do You Have Resources To Support The Solution

    Do You Have Resources To Support The Solution

    Our question checklist focuses on getting our problem solved and crafting that solution. However, we also need to support the solution. We want to avoid many pitfalls; the most difficult one to recover from is a lack of foresight. This challenge comes from keeping our focus on the initial solution without considering its downstream and long-term impact. 

    Impact Of The Solution

    When we answer the other questions in our checklist, we examine how we might need to create or change processes. Likewise, we incorporate the immediate impact. We often will project the value of those changes beyond the product launch. However, customers often overlook the need to support and maintain a system. That burden can rest entirely on the vendor, but often there is no way to avoid some of it falling on the end users or the customer. These burdens include everyday tasks like support and training that are easy to highlight and discuss. Nevertheless, they are often overlooked. Likewise, systems costs such as hosting, storage, backup, updates, and security are frequently missed. 

    Items Needed To Support The Solution

    Everyone loves a list in an article like this. So here are some questions we want to address to support the solution properly.

    • How is the source code hosted or version controlled?
    • Who owns the rights to the source code?
    • Where will the solution be hosted? What are the estimated costs for it?
    • How will backups and disaster recovery be handled?
    • What user support is provided/expected? What SLA is expected?
    • How will user data be administered?
    • What sort of staffing is expected of the customer? (or available)
    • How will future updates and maintenance be supported?

    Now And Future Resource Needs

    We need to address implementation resources before we go too far into discussing post-deployment questions. The decision of build vs. buy and initial configuration can be limited or at least weighted by current resources. For example, there is a significant difference in a company deciding to build their solution when they have an IT department instead of when they do not. Be warned this can apply to purchased solutions as well.

    Modern software is often complex and touches other systems. Integrating current or legacy systems can require advanced coding skills or a matter of drag and drop in a graphical user interface. The expectations and available resources must be identified early in the problem definition process. Those times might need some lead time or significantly impact costs and timelines.

    Determine Ownership Of The Solution

    The questions above help us define who will own the solution once it is deployed. That includes support and maintenance as well as future enhancements. While some of that can be deferred to later (e.g., version 2.0), it is essential to know who will be involved post-production. There are many reasons to want to own the support of a project. On the other hand, there are also many reasons to desire support to be outsourced. The vision for the system can be as crucial to your plans after deployment as it is running up to that deployment.

    Source code and related questions, including artifacts like technical documentation and build scripts, are commonly overlooked. However, I find most customers only do that once. It can be a harsh lesson to learn. That applies to whether you are handed the keys to the solutions and do not want them or when you want them and have to pay extra for that privilege. These details are critical to your decisions about how to support the solution once it is in production.

    Training, Documentation, and Building The System

    A final area it is worth highlighting is the above deliverables. It is not as common that the delivery of the artifacts is unclear as it is the expectations. There is a broad range of ways one can deliver documentation, train users, and build the final product. Be clear about what is expected and discuss it early in the project. I have seen many projects get to the end on time, and then training and documentation sink the project. Do not allow these to be pushed to the end of the project. Demand that there is work done towards these goals and time to review the materials well before the end of the schedule. Avoid these artifacts being delivered in a rushed fashion after the implementation group thinks they are done.

    Improve Software Success

    We have an e-book that can help you explore all the steps in building software, including a few templates. We will add you to our monthly newsletter, but you can unsubscribe anytime. Your data is not shared with anyone else. Learn more about our book here. We are happy to help you in your journey if you would like to invest a little more time into planning for your project. We offer free consulting to avoid seeing avoidable mistakes. Please take advantage of it and avoid being the next cautionary tale.