DEV Community: Tummala Krishna Kishore

What actually belongs in an architecture decision record (and what doesn't)

Tummala Krishna Kishore — Sat, 25 Jul 2026 06:35:30 +0000

Most architecture decision records fail for the opposite reason people think. The issue usually isn't that teams forget to write them. It's that the ones they write are filled with the wrong content. The key information a reader needs—why this option instead of the others—often gets buried on page three under a list of API changes.

An ADR has one job: capture a decision that is costly to reverse, along with the reasoning that led to it, while that reasoning is still fresh. That's all. It isn't a design document, a specification, or a collection of research. If you keep that focus, everything else about what to include or leave out will follow naturally.

The format that still works
Michael Nygard's original ADR template from 2011 (title, status, context, decision, consequences) has lasted for a reason. It directly addresses the key questions a future reader has: What was the situation? What did we decide? What did we give up? Teams that add ten extra sections, like owners, review dates, risk matrices, or approval lists, usually end up with a document no one finishes reading, which defeats the purpose. If your ADR template is longer than the time it takes to fill it out for a simple decision, cut sections until it’s more concise.

A useful rule of thumb is that an ADR longer than a page and a half is often a design document masquerading as an ADR. This isn’t a strict rule, but I haven’t seen a truly good ADR exceed 600 words. The decisions worth documenting this way can be stated, justified, and owned in about a page. If that's not possible, the record isn’t the issue. The decision is probably still tied up with other unresolved matters.

What belongs
The decision, stated clearly. "We will use event-driven integration between the order and inventory services instead of synchronous REST calls" is a decision. "The order service integrates with inventory" simply describes the current state and belongs in a wiki, not an ADR.

The challenges faced. Describe the two or three actual constraints that were in conflict, not a comprehensive literature review. For example, a latency budget versus consistency guarantees, team ownership boundaries versus a shared database that made those ownership lines unclear, or cost limits versus the vendor lock-in that comes with a cheaper option. If there was no real conflict, you probably didn't need an ADR.

The alternatives you seriously considered, along with why they weren’t chosen. Focus on the options a competent engineer would likely ask about six months later. For example, "We looked at a shared database with row-level locking; we rejected it because it recreated the coupling we wanted to eliminate between the two teams' deployment cycles." This simple statement saves the next person from rehashing a decision that's already been made.

The consequences, including the ones you’re not thrilled about. This is often the section teams skip, but it offers the highest value. Every genuine architectural decision comes with costs. If you adopt event-driven integration, you trade the simplicity of synchronous actions for eventual consistency and a tougher debugging process when a message is lost. Document that. An ADR that lists only the benefits isn't a valid record of a decision. It's a sales pitch to your future self, and future-you won’t be fooled more than once.

What doesn’t belong
Implementation details. Class names, endpoint paths, table schemas, retry counts—these change frequently and can quickly make the document outdated. If the ADR needs a code example to clarify its point, it likely indicates that the decision being documented is more about implementation than architecture, and it should belong in the code or design document instead.

Decisions that are not settled yet. If three options are still in play and no one has chosen one, that's a design document or a spike ticket. Writing an ADR for a decision still in progress creates a record that contradicts itself by the time it gets approved. Contradictory records are worse than having no records; they mislead the following reader.

A decision made after the fact to meet process requirements. This rubber-stamp scenario is more common than teams want to admit. Someone builds the solution and then creates the ADR retroactively because it's required by the checklist. The "alternatives considered" section becomes fictional, as nothing was actually considered. The option that got released is the only one that ever existed on paper. Readers can tell the difference. An ADR written after the code is merged feels different from one written beforehand. Once a team’s ADRs acquire a reputation for being just for show, people stop reading them, which is worse than never having them required.

Every decision, regardless of its importance. This is the trade-off people often avoid stating clearly: requiring an ADR for every non-trivial pull request leads to a pile of records. For example, both the choice to follow field-naming conventions and the decision to go fully async receive the same template and attention. The signal-to-noise ratio diminishes, and the truly important records—those concerning team boundaries, data ownership, or long-term platform choices—get lost among many similar entries about logging formats. Save ADRs for decisions that are genuinely challenging to reverse: those that affect team boundaries, data ownership, or a platform choice you'll live with for years. Smaller considerations can go in a pull request description or a design note.

The crucial test
Before you write the next one, ask yourself: if this decision turns out to be wrong in eighteen months, would the person troubleshooting it appreciate this document? If the answer is that they would skim through the generic content looking for the paragraph explaining why the obvious choice wasn’t made, write that paragraph first and build the rest of the record around it. Everything else, like the status field, review date, and approval chain, is optional. The reasoning is the key part; treat it that way, and the format will fall into place.

Open In-line video in fullscreen

Tummala Krishna Kishore — Tue, 01 Feb 2022 05:55:24 +0000

Its been a long time i have written my posts, so got some free time to publish some articles which are usefull for the people who are implementing In-line video and make it fullscreen in Ionic.

In the Config.xml we need to Add this Block of code to Make it full screen

<preference name="AllowInlineMediaPlayback" value="true" />

Which Triggers the Native app to play in Inline. while coming to the HTML5 there is a intresting fact that was stated in Apple Developer Site

on iPhone and iPod touch, which are small screen devices, Video is NOT presented within the Web Page

Publish from Visual Studio and automatically encrypt appSettings using aspnet_regiis

Tummala Krishna Kishore — Tue, 17 Aug 2021 06:04:18 +0000

After going through your all edits and a bit of research from me , you want to execute the following command after the publish from the Visual Studio

C:\Windows\Microsoft.NET\Framework\v4.0.30319\aspnet_regiis -pe "appSettings" -site Default -app "/"

If I understood right , You can try wrapping the ItemGroup in a Target with AfterTargets set to AddIisSettingAndFileContentsToSourceManifest

<Target Name="executeinHosts" AfterTargets="AddIisSettingAndFileContentsToSourceManifest">
    <ItemGroup>
      <MsDeploySourceManifest Include="runCommand">
       //here would be your path that need to run after the publish
      </MsDeploySourceManifest>
    </ItemGroup>
  </Target>

So in Your case this is how that part should look:

<Target Name="executeinHosts" AfterTargets="AddIisSettingAndFileContentsToSourceManifest">
    <ItemGroup>
      <MsDeploySourceManifest Include="runCommand">
         <path>C:\Windows\Microsoft.NET\Framework\v4.0.30319\aspnet_regiis -pe "appSettings" -site $(DeployIisAppPath) -app "/"</path>
      </MsDeploySourceManifest>
    </ItemGroup>
  </Target>

Additional Info:

AddIisSettingAndFileContentsToSourceManifest target works just right before Web Deploy copying files from local to server.
aspnet_regiis can be run in node by .

Example:

<Exec Command="C:\Windows\Microsoft.NET\Framework\v4.0.30319\aspnet_regiis.exe -pef connectionStrings $(ProjectDir)obj\Debug\Package\PackageTmp" WorkingDirectory="$(publishUrl)" />

Display datetime correctly in iOS/Safari using ionic2/angular2

Tummala Krishna Kishore — Tue, 06 Jul 2021 07:58:39 +0000

The issue is caused by the Intlapi because DatePipe for Angular 2. Release is working fine only for FireFox and Chrome with custom format strings. it Doesn’t work on Safari due to lack of Intl. so as a temporary work around is to include the Intl polyfill

<script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=Intl.~locale.en"></script>

Solution 2 You can use the moment.js which can format your required date as follows

moment(singleTable[0].FromCurrentDate).format("dd/MM/yyyy,h:mm:ss a")

Pass multiple Eval field in one command argument in Repeater Control

Tummala Krishna Kishore — Thu, 01 Jul 2021 10:11:47 +0000

This is the most common problem that generally users face while dealing with Repeater control. I gave this solution in Stackoverflow. want to post it here for users coming from search

Add the below snippet in in template

CommandArgument='<%#Eval("ScrapId")+","+ Eval("UserId")%>'

In code behind you can use retrieve values like this

protected void GridViews_RowCommand(object sender, GridViewCommandEventArgs e)
{
    if (e.CommandName == "Comment")
    {
        string[] commandArgs = e.CommandArgument.ToString().Split(new char[] { ',' });
        string scrapid = commandArgs[0];
        string uid = commandArgs[1];
    }
}