One post tagged with "Requirements"

One problem with software development is (and still is) that related artifacts are distributed across various tools. Tasks are set in Jira, documentation in Confluence, and code in GitHub or GitLab. The requirements and documentation are unequivocally spread across those.

If managed right, that is not a huge deal. Unfortunately, I rarely saw such cases in practice. Frequently, the requirements management on large enterprise projects goes rogue as soon as its initial owner/founder passes on. That contributes to a mental block that some developers had issues with (or simply don't like) reading requirements.

And I could relate to that: the additional cognitive load of tracking all the task details from various sources and putting them into one picture. Plus, those requirements might be badly written. Some context might be missed, taken for granted, and so on.

I understand those who ignore the specification and go directly to the source of truth or their proxy. Don't support, but understand.

Fighting in the war for unification, I became an advocate for the docs-as-code approach where appropriate. Your service docs, as Markdown files, are under the same Git versioning as the source code. As a definition of done, the developer updates the docs along with the code. They no longer forget to update the docs. Plus, the docs are in code and are more clearly structured. At least, on my projects.

That trick did not meet the requirement, though. I've never tried to implement that in practice; I only did a few thought experiments. My main issue is that, unlike the documentation, which aligns with the functional parts of an actual system, the requirements do not match the architectural design.

Simply put, requirements may span multiple modules, so where the heck am I supposed to store them? And if they concern several repos? My thought experiment ended up with a separate Git repository for requirements, which is the worst idea, even compared to Confluence.

Now, in 2026, docs are essential to the context for AI tools. So the proponents of docs-as-code had an advantage there, since they skipped a step involving Confluence MCP.

AI also changes the perspective on requirements.