Stop Searching for Truth

//Stop Searching for Truth

Separate piles of chips, representing information, are centralized by pushing them into one pile

How many places do you need to search to understand your company’s own software? I’m sure you have some kind of user-facing documentation or some form of presentable details that your users can work off of. That doesn’t describe your database schema. It doesn’t go into the API endpoints available for your partners wanting to integrate with your product. It probably doesn’t contain how the software is deployed into production. How about the list of external dependencies, which you need to scan when you learn a popular NPM package has a major vulnerability? Architectural diagrams or notes? Future work planned out?

Where do all of these details about your system live? Where is this metadata contained? How many different places (including coworker’s heads) would one have to search through to find out details necessary to accomplish work?

How much of your company’s time is being spent digging for Truth instead of building?

Centralizing the Truth

Spreading information about projects in multiple locations increases the likelihood of information going missing, not being updated, or otherwise falling into the gaps and getting lost. Missing information can lead to increased times to deliver new features as developers spend time rebuilding the knowledge necessary to complete their work.

Let’s call this Truth (capital T), representing the core information about what a project is and how it works. This Truth shall live in a central repository of some sort.

Not everyone in a company reads information in the same way. Sales documents don’t need to include deep API information, while architectural diagrams don’t need to be simplified for external viewing. The information that goes into these documents, however, is the core Truth of the system they’re describing. It’s this Truth that needs to be centralized, not necessarily the corresponding documents generated for specific business purposes.

Once centralized, a team can project this Truth into other forms for better use by different teams in the company. The core Truth of the project’s information, however, should reside in this central repository in a format most effective to project it into other details.

Fortunately that’s precisely what Azure DevOps is working towards.

Code and code-adjacent information

The core Truth of any technical project is, of course, the code itself. Most of the rest of the aspects of these systems can be divined by a thorough study of what the code is trying to accomplish. In lieu of relevant and available documentation the code is a last resort source of Truth.

Many teams are already familiar with storing code in a centralized way. After all, the entire team needs to be able to work on the code. They also need to stay on the same page as they work on the code. Git (or TFVC) provides the tools to work together on Code Truth without losing information to the aether.

Azure Repos is the place to store this information. Git provides an excellent means to store and work in teams with code or other text-based files. We’ve worked with companies that maintain documentation, XML-based configuration files, even text-based database files that an IBM product used to generate geographic datasets and map files.

When the code is securely stored in a central way we can then project this Truth into other forms, such as with a build and deployment pipeline.

Build and deployment instructions

Once your code is stored in a Truthful way the next question might be how your code gets out into the real world. A git repo of web code doesn’t display a very pretty webpage. Instead, we must take the Truth, in the form of code, and modify it into an artifact of that Truth, a Build.

Azure Pipelines are split into two aspects of this: a build and a release. A build will transform raw code into a presentable form for consumption by a web service, or an installer, or some other external utility a user interacts with. The release places this artifact in a location that the user can access it, such as an App Store, or a webserver.

We haven’t really changed the Truth here, it’s sourcing from the same Truth that the developers have created. By automating builds using Azure Pipelines we gain the ability to only ever rely on the code as a source of Truth. There are no other inputs into this process: just the code and its pipeline.

That pipeline however is another source of Truth in and of itself. One needs to know the steps and instructions necessary to project the code into its presentable format. Pipelines has an answer for that in the form of YAML pipelines. Azure DevOps has recently expanded the capabilities of YAML in Pipelines and made it easier to store pipeline descriptions in code.

Once the pipeline is stored in YAML code the project is a closed loop from where a programmer writes the code on their machine and where the code is running in front of the user. That’s written out in a way that can be referenced for all to see or link to.

We may not want to show raw YAML or build status pages to non-programmer staff though, as they likely don’t want to look at that to see whether the software is up to date on the web server or app store. Instead, we might present the results on a dashboard. This allows us to project the Truth of release status into a form that other teams can use for at-a-glance status.

Project planning

The code is stored and a pipeline can be run whenever your team wants to put code out into the world. Now one of the other major pieces comes into play: the plan around what is being done to the codebase. The ability to quickly jot down notes and status updates for these plans is important: the more difficult the tool the less likely people are to use it.

Azure Boards offers a variety of tools to easily track a team’s progress while working on projects. The work item forms allow pasting of images in the description and files as attachments, so that nobody need dig through a poorly maintained shared folder. Branches can be created right from work items to track work on a story or bug. Work items can be arranged into Scrum, and displayed on Kanban boards customized to each team.

Each work item in the system has a commentary field, allowing for rapid updates of status or recordings of conversations. One need not limit discussion to this area. Using the best communication tool at hand, be it Slack or shouting across the office, need only be adapted by jotting down the results of those conversations in the ticket itself. This momentary act can help keep everyone on the same page.

Project the Truth elsewhere

Once these three sources of Truth are being used and maintained it’s only a matter of using the Azure DevOps integrations to project this Truth out among your teams.

Maybe Slack is more your team’s speed for communication? Integrate with it to help maintain the centralization of Truth.

Some members of your team preferring Trello for kanban instead of the Azure Boards view? Link it up so that the source of Truth remains in one location.

Already using GitHub as your Code source of Truth? Link up to Pipelines to jump right into build configuration as code.

Once you’ve centralized the location of your to Azure DevOps, it’s easy to send that Truth out into the world in whatever format is necessary. All it takes is committing to bringing the Truth back home where it belongs.

Need help finding your Truth?

Nebbia has helped many organizations reign in their sources of information and streamline their recording of Truth. Drop us an email or phone call and we’ll be happy to take a look at how we can reduce the time spent finding information in your company.

By |2018-10-26T18:10:41+00:00October 26th, 2018|

About the Author:

Cliff Chapman is a C# developer, unit tester, Selenium writer, code slinger, problem solver, outdoor camper, road trip driver, and a number of other -ers. He specializes in semi-functional programming with an eye towards automation and shortening feedback cycles. Often he can be found arms-deep in a problem (sometimes literally) trying to solve it on time and make everyone happy.