Voice of the DBA

Tag: software development

  • Creating Documentation

    Who should create documentation for software? In many companies, it’s the developers. In fact, in Redgate, often our developers are tasked with updating articles for products on our documentation site. We do have a streamlined process that has developers can submitting changes in some format (markdown? ) and an automation process that automatically updates the site as part of a release.

    However, we also have marketing people who are in charge of external articles and communications. They ensure that our product learning and university content is updated. They work with technical people to produce, edit, and publish content. These could be developers, advocates such as Grant or Ryan, or even partners. Our Friends of Redgate also help with content.

    Who should write and update documentation? Developers might best know how software changes, especially for new features. I know that developers also hate this chore, and I think they often don’t have the best perspective because the documentation should explain how I use things, not how I built them or just how I expect them to work. Developers sometimes just want to document how they expect the software to work.

    At the same time, marketing or some other area might not be aware of changes, necessitating more handoffs from the development teams. That can be a bottleneck in a DevOps flow. Of course, some of this process could be automated, like sending release notes to marketing. However, there is also the need for someone technical to review changes, which can require more resources. It could also mean marketing people ask developers to review changes, taking up their time anyway. If developers are like me, then they might just want to handle it themselves than communicate changes and still have to review someone else’s writeup.

    There probably isn’t a hard and fast rule. Not everyone communicate the same, or even that well. Writing is a skill, and while I might ensure all developers work on this skill, I might also try to lean more on those people that communicate well to ensure docs are updated for our clients.

    If you are building internal software, perhaps you forgo documentation entirely. I could see developers having a meeting with either QA staff or perhaps a business person to teach them what is changing. Then this person gets tasked with training others on the software rather than ensuring any formal documentation exists. Tribal knowledge might be the best solution here.

    If you’re a developer, would you want to control documentation or avoid it like the plague? Let me know today in the comments.

    Steve Jones

    Listen to the podcast at Libsyn, Stitcher, Spotify, or iTunes.

  • Living With Broken Software

    I travel quite a bit every year. Over 20 trips in 2022 and five trips in the first quarter of 2023. To make life easier, I have a few routines that I use to ensure that travel goes smoothly and I don’t forget things. One of those routines is using a parking service near the airport.

    This company used to have a fairly manual process, though it improved over the years. The pandemic forced them to move to more contactless service, which I appreciated. I could make a reservation online, get a QR code, and use that to both enter and exit the facility without interacting with anyone or handling money. A bit safer, but the big win for me was that this process was quicker for me move into and out of the lot.

    This service worked great in 2021, but sometime in the spring of 2022, I was making a reservation on the mobile app on the way to the airport. After completing the form, I clicked submit and got an error. I wasn’t sure what to do, so I double-checked everything I’d typed and resubmitted.

    Again, an error.

    I tried a third time, feeling a bit frustrated. I’d stopped for coffee and needed to start moving to the airport. For some reason, I decided to check my email. To my surprise, I found a confirmation of the reservation. Actually, I found three, which necessitated me asking for refunds for the two I didn’t need, while then trying to ensure I actually used the correct QR code to get in and out.

    Since then, I’ve used this mobile app multiple times to make reservations, and it always errors but sends a confirmation. I’ve sent a note to the company, but nothing has changed. The web app doesn’t seem to want to work correctly either but has different problems. I’ve tried a couple of other services, but I like this one. I just need to remember to make one reservation, ignore the error, and check my email.

    The tech is broken somewhere. Yet it works. It’s mildly annoying for me, perhaps much more annoying to others. This might dissuade new customers from using the service, though the parking lot seems fairly full most of the time. It’s the kind of thing that I, as a software developer, would want to fix.

    It’s also the kind of thing I could see management not caring about, and instead asking me to focus on new features or other bugs that are preventing customers from using the service.

    There is often more work queued up for software than there are time or resources to tackle them. When anyone is building software, they are constantly making choices about priorities and focus. What do I work on? What should be done first? What bugs need fixing and what bugs can we live with? Working for a software company has helped me keep perspective on the larger picture for a business.

    At the same time, I feel the frustration of a customer when things don’t work as I’d want them to work. Especially when an error is involved. This seems like it should be an easy fix, either catch the error and do something, or at least swallow it from the customer perspective. However, I have no idea how widespread this error is, or if I’m the only one for whom it doesn’t work. A good DevOps process would have instrumentation and monitoring to learn the scope, scale, and criticality of this, and other, bugs.

    Either way, it’s been alternately annoying and humorous to me. It works, and I live with it, sometimes amused that it’s still occurring. Perhaps I’ll even miss seeing the message when or if it gets fixed.

    Steve Jones

    Listen to the podcast at Libsyn, Stitcher, Spotify, or iTunes.

  • Metrics and Measures

    Many organizations have been trying to find better ways to build and deploy software for their customers. Whether they deal with the general public or internal customers, we know that delivering software that customers use can be a competitive advantage. That’s the goal of DevOps.

    While most developers and management want to do this, they sometimes forget what the goal is. Instead, they want to continue to work in a similar manner themselves while giving lip service to actual change. They often do this while pushing others to somehow produce more and better software inside the same system. I see this over and over inside various companies.

    To become better, many of us use metrics and measurement of data to help guide us in determining how to move forward. In the area of software, there are a number of research reports showing which metrics are indicative of organizations that do a good job of delivering value to their customers. There are four main metrics: deploy frequency, lead time, change fail percentage, and mean time to repair. These are highlighted, though there are plenty of other things to track in your software process.

    However, aiming to just improve their metrics as the primary goal isn’t going to make your software better. The goal is to deliver software that meets your customers’ needs. Quicker, better quality, more features, and all those things that customers use are what is important. These metrics are there to help guide you, not to be the targets of efforts.  There’s a good article that talks about some of the downsides of just trying to improve these metrics.

    The goal is the continuous delivery of value to customers. The way we do this is by experimenting with code, getting rapid feedback from customers, adjusting and improving the code, and repeating the process, learning from our efforts. We drive automation to make this smooth and easy while enabling us to get our software to customers at the pace that suits our situation. It sounds vague and amorphous, and it is.

    There is a bit of an art to developing a process that efficiently builds software. It depends highly on the people involved, and on two other things. First, guiding them to improve their process and skills with references to practices that have worked well. Second, giving them the freedom and support to experiment and learn from their efforts. In doing those two things, it’s important to remember that while you can measure how well things are changing, aiming to improve the measurements often doesn’t help you improve the goal: building better software.

    It’s good to measure things, but keep in mind that the measures are not the goal.

    Steve Jones

    Listen to the podcast at Libsyn, Stitcher, Spotify, or iTunes.

  • Coaching the Digital Transformation

    One of the challenges for me when working with customers is getting them to think about how to change their software process. Often they want to solve their problems, but no one wants to alter the way they work. Whether that’s the protocol for capturing code or managing servers, it seems that changing the way we work is hard for many people. They want everyone else to change. Or they want a magic tool that solves problems without them changing the way they work.

    Unfortunately, I’m not a magician.

    This is a common problem in many organizations. We want to be more efficient and effective, but actually changing our habits and culture is hard. Management should lead the charge, and they want to, but they can struggle with how to do this. Often they focus on changing technology, and not actually improving the way their company works.

    There’s an interesting article on digital transformations and whether the efforts are worth the investment.  In many companies, someone makes a good argument for a course of action or a project and then drives it. Others participate, but often a person pushes this forward, usually because they have some stake in the outcome. A bonus, a reputation, or just pride, whatever matters to them becomes the reason for continuing, even if there isn’t enough value from the effort. This can be because of an institutional culture that wants to finish projects, wants to find some success in a course of action. Whether a human or an organization, pride and inertia often keep us moving forward, often without any other support or analysis of how well things are progressing.

    Effective dashboards enable everyone to see current status and progress, and to make better course corrections, helping to move from a command-and-control model to a coach-and-communication orientation. Many organizations have adopted KPIs, dashboards, and other ways to analyze parts of the business, but this isn’t always something we do well in software development. We tend to look at metrics that management cares about, and on which we are measured, rather than metrics that might help us improve how we work.

    Part of digitally transforming a business is also transforming how technology is used. Part of that is us, as technologists, learning to be better and more effective. Whether this is in development or operations, we can often improve how we function. We need coaching, and in many orgs, that coaching has to come from within, from the people in a team asking others to do better. And to allow others to ask us to do better .

    Coaching is often teaching from a different perspective. It’s helping someone see what they don’t see themselves. This might be new knowledge, but many times it’s just reminding the individual of something they know, but aren’t doing. As we are asked to do more, be open to coaching and be willing to help coach others. Become a role model that helps transform how your organization uses technology.

    Steve Jones

    Listen to the podcast at Libsyn, Stitcher, Spotify, or iTunes.