In this article, I want to look back on the evolution of how we managed project documentation, discuss one non-obvious problem of working with AI that few people think about, and show how to combat it. And at the end, I'll share useful materials—a documentation repository example for two approaches (classic waterfall with Kanban elements and pure Scrum) with a ready AI skill for analyzing code changes.
Evolution of documentation: from network drives to Git
Right off the bat, I'll make a disclaimer: the beautiful evolution I'm about to describe happened exactly in my career. Of course, Waterfall was replaced by Scrum in global practice long before I started working as an analyst. But, having switched through numerous projects and gone through hundreds of interviews, I've accumulated a sample that shows common trends.
The Word and Email Era
When I first joined systems analysis 8 years ago, we wrote documentation in Word and sent it via email for approval. It was stored on network drives or in Google Drive. Versioning was done directly in the filename (ТЗ_v1.5_final_FINAL.docx). Customers left comments directly in the document, often in text with colored highlighting, and we transcribed them into Excel tables and manually set the status of resolved open questions after meetings for internal control.
Documentation was classic, according to Wiger: separate document Vision and Scope, separate business requirements, a huge Functional Requirements + Technical Specifications (which grew by 250 pages a year), user instructions with a million screenshots, and detailed acceptance testing program. On projects with government clients, it was the same Word, but with strict formatting requirements according to GOST.The Era of Confluence and Scrumban
Then came a series of projects with documentation in Confluence. Both clients and we learned to work with it, comment registers naturally died off—comments were conveniently highlighted directly on the pages. The process became closer to Scrum-Kanban: increments, sprints, Jira boards, but without strict rules of classic Scrum. Documentation split into three spaces: requirements in progress, current system state (AS-IS), and user instructions.
The Era of Git, Stickers, and AI
Now I observe a new stage of evolution. Documentation is becoming smaller, knowledge bases are moving from Confluence to Git (in the Docs-as-Code approach or at least in markdown formatting), schemas and comments in code gradually replace text, meeting records and auto-protocols replace the traditional "No Objections" email-confirmed meeting protocols. Requirements are often only recorded on stickers in Figma and in Jira tickets, and updates to the current system state are directly entered into documentation.
But a new problem has emerged. Documentation is already being generated through AI, and often isn't generated at all, based on the thought: "AI will read the code anyway."
In my opinion, AI has not yet solved the main function of an analyst—maintaining context. On the question from a manager "Why did we do this and now it's interfering with working on that?" we still have to dig through boards, protocols, code, and call on the team veterans.
Main insight: For whom are we now writing documentation?
This week I was reworking a huge volume of documentation generated through AI. And I was reworking it... also through AI. Writing by hand is becoming less necessary, but neural networks are just a tool, not a knowledgeable team member responsible for documentation.
Recently, we discussed with the development lead. He asked: "What are we going to do with documentation next? Are developers going to read it?"
Most likely, they won't. They will continue reading code and chat messages. But here's what's truly important: besides business users, documentation will also be read by AI in the next iteration of updates.
What AI typically puts into the documentation (diff description, affected methods, used APIs) is practically useless for subsequent reading. The next AI agent, when planning updates, will look at the code itself, just as a live developer would.
But we, analysts, understand that the question "What changes are needed where?" isn't the first one. The first question sounds like: "Why do we need exactly these changes, are we sure about them, and what impact will they have?"
This is precisely the knowledge layer that lived in the heads of managers, analysts, and in analytical documentation. When shifting the process towards product engineering, it risks disappearing the fastest. If a developer receives a task from business and immediately starts implementing it with AI, the machine will figure out how to technically do it. But she will not critically evaluate the proposal itself, and often will not even evaluate its architecture, if the developer does not set such a goal. In a large enterprise, this leads to a snowballing technical debt, where stickers are attached where there was never any logic inside, just a placeholder for future refactoring, about which everyone forgets in the next sprint.
How to avoid chaos: from prompts to skills
The first step is already done—we have moved the documentation into Git (Markdown) and update the data right there. AI will be able to work with such a database and search for artifacts of previous decisions.
The second step is creating AI skills. A skill is a preconfigured instruction for an AI agent that defines the workflow and quality criteria. It is impossible to embed years of expertise and the mindset of a senior analyst into the instruction, but such a skill will save hours of review and force the machine to maintain business context, not just list the affected endpoints.
It is important to note that creating the skill itself is not the main challenge here. Any AI will create a skill for your exact request with a list of rules in 10 minutes. It is also important that its use becomes ingrained in the processes. In my case, the base was already prepared: the company is actively moving towards the concept of product engineers independent from anyone else, repositories with various skills are already being prepared, and almost no one is writing code or documentation anymore. Nevertheless, I took the following steps:
highlighted the problem with management to justify my time investment;
raised the issue in the community of analysts and took the initiative to prepare a skill;
developed the skill myself and poked analysts several times to ensure they were at least not against it;
discussed the correct placement of the skill and the placement of all references to it in the general repository with the lead developer, so that it wouldn't gather dust in our repository, which no one visits anyway, but was included in the flow of AI feature development.
Will this help make the documentation perfect? Unlikely without people interested in it. Developers will still not focus on it if management doesn't consider it important. But at least including reminders for agents in general skills will allow making the documentation non-zero, which is already more useful than nothing. Further, I hope that when the first difficulties arise with further work without storing the history of decisions made, management will also think about it and focus not only on getting everything done as quickly as possible, since without analysis and documentation, the quality of the final product suffers.
Practice: Templates and AI Skill for Your Team
I prepared a public repository with my approach to organizing documentation in teams working with AI. Templates define the structure, and skills define the AI's workflow for interacting with it. A human checks the result and makes decisions.
In the repository, there are two sets for different needs:
1.
Hybrid Kit (Iterative Development with Detailed Coordination)
Suitable for teams that need to coordinate changes with the business stakeholder and maintain a description understandable without reading code.
Feature: The refinement process goes from business requirements and functional tests to an architectural decision record (ADR). Documentation allows understanding of the system's behavior regardless of the original task.
It is aimed not only at the team but also at external stakeholders who can read the text and understand whether their requests were implemented and how.
This kit is more oriented towards writing and reading by humans, but the skill can also be applied to it, reusing the skill base from the second project.
2. Scrum Kit (Up-to-date Documentation for AI Teams)
The developer works with the AI to study the request, determine the product impact, and update related documents directly during implementation.
Feature: Implementation details remain in the code, while the documentation (in cross-cutting business processes and AI Context blocks) preserves the business meaning, reasons for decisions, and connections. This is an ideal context for AI.
In the repository, there is a ready skill document-scrum-mr. This is an instruction for the agent analyzing Merge Requests.
How it works: you pass this skill to the agent, a task from the tracker, a code diff, and access to the working documentation.
Agent:
Compare the implementation with the business goal.
Clarify the missing reasons for changes.
Determine which Markdown files need to be updated.
Prepare a coordinated set of edits and update AI Context.
You only need to conduct a human review (for example, get two approvals from the team).
Link to the repository with templates and skill
Materials are available under the CC0 1.0 license — take them, adapt them for your projects, and share with your colleagues.
And what do you think?
Do you already have experience writing such analytical skills? Or is there no one in your company who is ready to cut and automate? Share in the comments!
