AI intro 8 - Product docs with AI

Human made doc

Normalized prose based on the original call transcription. Only the relevant fragment about working with product documents, Markdown, Codex, transcriptions, and Neuronet was used for the lesson.

There are people who already write in a Markdown format that is more suitable for AI: so that they have the superpower to create knowledge bases in their Codex or Claude Code for every area of their product, and so that AI models can read this knowledge base nicely, search through documents, and use them as context.

And there is a more product-oriented approach: Confluence, where documents are written primarily for people, so that people can read the documents. That is, Confluence has long been used as a human knowledge base, while Markdown is gradually becoming a format convenient for AI Native work.

Here it is important to understand that we have previously tried virtually all product documentation formats: MS Office, BaseCamp, Notion, Google Docs, Confluence, documents with images, documents with arrows on screenshots, video, Loom, and so on. At some point, Loom became the peak of evolution: you do not just write text, but tell the story and simultaneously show what is happening on the screen. In the Loom format, it is extremely convenient to create product presentations, record ideas, explain tasks, and make instructions.

But Loom and Google Meet have a common problem: people talked, someone watched the recording, someone did not, someone understood something, someone did not understand or forgot, and after a pleasantly spent time everyone went their separate ways. This approach is not enough for effective product work. A conversation by itself does not turn into durable knowledge that can be reused by all team members at any time.

At the same time, AI appeared, and people learned to generate documents. This led to another problem: AI slop. Kilometers of text are generated that nobody wants to read. Even before, it was difficult to make people read ordinary, human-made, large documents, but now it has become even worse: a person sees an AI slop text, understands from the first paragraph that it was generated by a model, and does not want to read it or spend time on it. It turns out that AI can produce text, but product work does not automatically become better because of that.

The question is actually different: how to feed documents to AI properly so that it really helps run product work. Documents are still needed. But they must be structured in such a way that an AI model can search through them, answer based on them, assemble context, and help new people quickly get into the project.

My simple experience is this: product work lives in Codex as a Product folder. A very important principle: a project in Codex must be tied to a real folder on the local disk. That is, I create a Codex folder on my computer, create a Product folder inside it, and then create a project in Codex through existing folder and specify this local folder. The result is a simple connection: a project in Codex equals a folder on the local disk.

The next step, to synchronize your local folders within the team with one another, is to create a Git structure in your Product project and upload updates to the team’s Github after each work session. Other team members update their local folders before starting work and make commits to the shared Github when creating updates or new documents. Developers work with code updates in roughly the same way.

Then the magic begins with organizing your Product folder into separate chats, which are also called agents. You create many chats in your Product folder for every product topic you need in your work. There are no rules here; you can use stakeholder kickoffs, team syncs, or syncs with other teams as topics. For example, we have a PRD document. I create a separate chat (agent) for the PRD and start putting all source materials related to the product work on the PRD there. This way, you upload all the source information into this chat, and AI Codex now knows everything necessary about the context of working on your PRD document.

And what source materials do we most often have at the start? First of all, Google Meet—that is, conversations from work meetings. Shurick comes, holds a kickoff, and assigns a task. Then we discuss the task with the team, and we get several Google Meet recordings as the primary source. Very high-quality information, because it comes firsthand.

If a new topic appears, for example PlayCanvas, I create a new chat (agent) in the Product folder and write directly: we will do all product work on PlayCanvas here. After creating it, be sure to rename the chat correctly and briefly, so that it is clear what work is being done in it. It is important not just to store MD files in Codex, but to create a proper workspace where Codex understands which topic we are currently working with.

For Google Meet transcription, I use the Command Center mini-app. Xsolla has a culture of mini-apps and design prototypes: through Neuronet, you can vibe-code automation for your internal process. I use Command Center specifically to turn Google Meet recordings into transcriptions in the format I need.

Previously, the work looked different: you had to record a kickoff, then review it yourself, study it thoroughly, extract the important parts, and assemble a document. I still work manually with important kickoffs from Shurick because the priority is high, but for dozens of calls every week, the processing process itself has changed. Now you can take a transcription of an hour-long meeting in MD format, upload it to the required Codex project and chat, give the local agent context, and ask: give me a summary only regarding the topic I need. If a lot of things were discussed at the meeting but only one segment is important to me, the agent helps quickly extract exactly the relevant part. This saves an enormous amount of time. Everything works in three clicks: transcribed, added the MD file to Codex, dictated one minute of context and a processing task, received a finished result in an MD file or directly in Confluence through a Skill.

For this, I have Google Calendar connected in Command Center. I can take meetings, transcribe them, turn them into Markdown, and then distribute them to relevant agents in the Codex folder of the Product project. These MD files become the source layer of information: not a polished document for the sake of a document, but material that can be uploaded into the relevant Codex agent chat, processed into an MD file, and put to work further—passed to Neuronet, used to create PRDs, architectural decisions, answers, and other product artifacts.

The important goal here is not simply to make a bunch of fashionable Markdown files. The goal is for the entire team to work with the same information. And not only the team, but the entire company: within the company, there are many people who can ask Neuronet something about Metasites. If we take the best answers, PRDs, architectural decisions, transcriptions, answers, and tell Neuronet: upload and update all information about Metasites, then it remembers this layer and can subsequently answer based on it.

As a result, we get a clear information knowledge base: documents, architectural decisions, PRDs, questionnaires, answers, additional PRDs, and other materials. This is important because stakeholders, top management, partners, game developers, and other process participants ask Neuronet questions. If someone needs to learn something, they do not have to DM one of the product people; they can ask Neuronet from the company’s shared AI base.

This is how we achieve the big goal: all 1,600 people get access to the same information. Before AI, such processes often worked like a game of telephone: seven people talked, decided something, while everyone else was unaware. In large teams, this is a classic problem. The farther the information transmission chain goes, the greater the gap becomes between those who conceived the product and those who later have to work with it.

Markdown files, Codex, and Neuronet help create a source information layer that is accessible to everyone. Moreover, anyone can take this set of MD files as a Source of Truth, upload them into their Codex or Claude Code, and be 100% in the same context as the core product team. This is especially important for new project participants: a person can install Codex, create a project, upload the materials there, and start asking: what is happening, which decisions have already been made, where is the North Star, which PRDs exist, what discussions took place at the kickoff.

That is why I try to keep all information about Metasites in Markdown. This is needed not only by product managers but also by developers. Developers resist new AI processes more strongly, but it is still important that even the developer most distant from the product understands the project’s North Star and sees where we are going. Not only three product people should know what our task is and which ideas we came up with; the entire team should have access to the big picture.

I also upload these same MD files and ask Neuronet to remember them. This is how we solve our product problems and simultaneously spread their solution across the entire company. We get not just a set of documents, but a shared AI-readable layer: people can read it, it can be uploaded into Codex, questions can be asked about it in Neuronet, and PRDs and other working documents can be assembled from it.

AI intro 8 - Product docs - Goals & Answers

Source of Truth

Now for an important block: what to do after we have added the document title to the required Codex chat or agent and uploaded all source materials there. Source materials may include Markdown files, Confluence documents, old PRDs, transcriptions, answers from discussions, and any other documents related to this topic. Simply uploading them is not enough. After that, you need to set a goal.

Best Practice

The goal is formulated very directly: please find the best practice in Confluence for the document we need. For example, if we want to make a PRD, an architectural document, a development task specification, or another product artifact, we ask Codex to find corporate best practices specifically for this type of document. Codex searches for existing requirements, how this document is usually made in the company, which sections are mandatory, what quality criteria exist, and which examples already exist.

After that, Codex must explain to us how to create this document correctly in accordance with corporate requirements. This is an important step because we do not want AI simply to invent a nice structure out of thin air. We need the future document to rely on a real corporate format, accepted best practices, and the way such documents are already written within the company.

Template

The next step: we set a goal for AI and say, please create a template for the document we need that conforms as closely as possible to best practice. At this point, Codex already knows which document we need, has seen the source materials, and has studied the corporate requirements. Therefore, it can create not a random template, but the most precise and high-quality template for the target document.

This template must be checked manually. You need to look at whether it suits your task: whether it is large or small, too broad or too narrow, whether it has enough sections, whether it is overloaded. If you need a short document, the template should be shortened. You can say directly: make this template more compact; we need a short working document. If you need a maximally detailed document, for example for a development task specification, then conversely you need to ask to expand the template: add more sections, more details, more completion criteria, more space for risks, dependencies, and open questions.

At this step, you adjust the target template to your task. This is not a mechanical operation. Here, the product person needs to look and feel: will this template really help assemble the document we need, or is it taking us in the wrong direction? Codex can offer a good foundation, but you decide what level of detail is required.

Questionnaire

When the source information has been uploaded, best practices and corporate requirements have been studied, and the template has been created and adjusted, you need to say the most important phrase to Codex: now please compare this template and all source information and check which information we are missing in order to fill out the template completely and with the highest possible quality.

After that, you need to ask: for the missing information, please create a questionnaire, that is, a questionnaire with the required number of questions. Codex should take the target template, take all source materials, compare one with the other, and understand where there are gaps. Which sections can we not fill in yet? Which decisions have not been recorded? Which assumptions are unclear? Where are we missing a business goal, user scenario, technical constraints, metrics, risks, dependencies, acceptance criteria?

At this step, you need to be careful. Codex may create a questionnaire with 200 questions, and it will be extremely difficult to work with such a document. In my view, the optimal number of questions for a good product or document elaboration is about 40–80. That is enough to think things through well and extract missing information, but not turn the process into an endless survey.

As a result, Codex creates a separate MD file with questions. This is not simply a list of curious questions. It is a list of the information it lacks to achieve the goal: to fill out a specific template based on specific source information. Such a questionnaire becomes a bridge between raw sources and a high-quality final document.

Answers

The next step: we put this MD file with the questionnaire into Codex and say: now ask me according to this questionnaire, one question at a time, and write the results into the answers file. And this is where the most valuable part of product work begins.

First, product work becomes voice-based. Codex asks question 1, and you answer by voice. Then question 2, and you answer. Then question 3, and you answer. You can answer alone, or go through the questionnaire together with the team. You do not need to sit down and write an ideal document immediately. You simply answer what you think about the questions asked by the questionnaire.

Second, product work becomes much more precise. This is no longer AI slop, not a generated wall of text, but your product information from the primary source: from the product team, from the owner of the direction, from the people who truly understand what is happening. Codex does not invent the product for you. It helps ask correctly, collect, and structure what you know.

This is a maximum life change for product work, because you no longer need to write documents “from a blank page,” which has always been incredibly difficult and labor-intensive. And you do not need to generate AI slop that is disconnected from the context of your product. You yourself, firsthand, create content with your voice based on your knowledge, thoughts, and ideas.

During the answer process, you need to monitor the quality of the questions. Over time, you will begin to feel whether good questions are coming or not. If the questions repeat, are too monotonous, too abstract, or do not help you think, that is not a problem. You can immediately tell Codex: these questions are too monotonous; make the questions more precise, more product-focused, more diverse, on the essence of this topic or another one. The questionnaire can be adjusted on the fly, and after that the following questions will become more and more precise.

As a result, you get a very strong answers file. In essence, it is the primary source of product information. It is firsthand information from the product team. Such a file can be used as the source of truth for the project: uploaded into Neuronet, given to new people, added to Codex, and used as the basis for future documents.

Only after this do we move on to the final document. The final command sounds like this: fill out the template based on our answers and based on all source information. Now Codex is not working in a vacuum. It has corporate best practices, a target template, source materials, and the product team’s answers to questions that close information gaps.

That is why the final document is no longer AI slop, but a high-quality document in substance. It is assembled from real information, verified through questions, structured according to the correct template, and matches the format the company needs. This is a fundamentally different level of work compared with asking “write a PRD” in an empty chat.

After generation, the final document must be checked. You need to apply a skill or a separate pass to replace typos, especially in terminology, because product documents often break names, internal terms, product names, and technical wording. Then you need to read the document yourself.

When you learn to do this process well, final documents will turn out very precise, and you will be able to review them quite quickly. But in the first stages, it is better to proofread carefully. This is how you will begin to feel where AI does not transfer your thoughts and ideas with sufficient quality, where it smooths over an important detail, where it interprets an answer incorrectly, and where you need to adjust the prompt for creating or filling out the template.

I strongly recommend using this mechanism. It helps everyone stay on the same page. Not only the three product people who discussed the product in the meeting, but the entire project team and the entire company. We get a shared way to turn conversations and fragmented sources into high-quality documents, answers, source of truth, and a shared product knowledge layer.

AI intro 8 - Product docs - workflow

If we formulate the practical workflow, it looks like this.

First, create a local project folder and connect it in Codex through existing folder. It is important that the Codex project be connected to a real file structure rather than existing somewhere abstractly.

Then create thematic agents—chats—within the project: PRD, architectural decisions, answers, sources, kickoff, separate product directions. The names should be understandable because this structure will function as a map of the project.

After that, collect primary sources: kickoffs. Google Meet transcriptions, Loom, notes, old documents, Confluence materials, links, answers from discussions. You can put them into thematic folders, or simply add them as attachments to the correct Codex chat or agent. At this stage, there is no need to try to make the perfect final document immediately. It is important to collect a complete source layer of information.

Next, turn calls and meetings into Markdown. For this, you can use Command Center or another mini-app for transcription. The main thing is that the result is textual, stored in the project folder, and accessible to Codex.

Then ask Codex to find corporate best practices for the target document: a PRD, architectural document, task specification, strategy, or any other format. Codex must understand how such a document is usually made within the company.

After that, ask Codex to create a template for the target document based on the best practices it found. Check the template manually and adjust it: make it shorter if you need a compact document, or more detailed if you need an in-depth task specification.

Then ask Codex to compare the template with all source information and determine which information is missing. Based on these gaps, Codex creates a questionnaire—an отдельный MD file with questions. It is optimal to keep the questionnaire roughly within the range of 40–80 questions so that it is sufficiently in-depth but still workable.

Next, ask Codex to ask questions from the questionnaire one at a time and write the answers into answers. At this stage, we provide firsthand product information by voice or text, while Codex carefully collects it in a structured file.

After that, ask Codex to fill out the template based on answers and all source information. This produces a final document that is based on real sources, corporate requirements, and team answers rather than empty generation.

At the end, check the document: proofread it, apply a pass for typos and terminology, and see whether the ideas have been transferred correctly. If we see that AI has not understood an idea precisely enough somewhere, adjust the prompt or return to the answers.

And finally, upload the selected and normalized layer into Neuronet or another shared AI knowledge base so that not only the document author, but the entire team can ask questions and receive answers from one source of truth.

AI intro 8 - Product docs - Markdowns

Now separately about the structure for storing product documents. We are creating a new structure according to AI-first principles. All document source materials must be in Markdown. This is important because Markdown is equally easy to read for a person, Codex, Claude Code, Neuronet, and other AI tools. For convenient manual reading of Markdown, you can use self-hosted Obsidian or Sublime Text. The main thing is that documents remain simple text files that can be stored in a repository, committed, read, searched, and uploaded into AI.

To work with such documents, every participant can create a project in their Codex or Claude Code and sync with this repo. You can commit, but there is an important rule: do not edit documents that have already been made without a separate reason and agreement. If a new product document is needed, we do not rewrite the old one; we make a new file with a note about the new version. This preserves history, makes it possible to understand where the information came from, and does not break already recorded artifacts.

The folder structure is organized by the role of documents. The top level divides materials into source of truth, secondary documents, calls, and then folders for specific product documents that are currently relevant and being prepared. That is, the most valuable primary information is stored separately, secondary materials separately, calls separately, and working folders separately for specific PRDs, ADRs, strategies, task specifications, and other documents.

Within working folders, a simple language rule applies: English files are located in the root, while Russian files are located in the RU folder. This helps avoid mixing versions, find the needed file faster, and avoid creating chaos in names. If a document is prepared in two languages at once, the structure should immediately support this separation.

All documents are now not written from a blank page. We create them through the process already described: give Codex or Claude Code a request and source documents, ask for a best practice template for the needed document, load all relevant MD files, ask it to determine what information is missing, and create a questionnaire. If the questionnaire turns out too large, for example 100+ questions, it should be adjusted. Usually about 50 questions are enough, sometimes 40–80 if the document is broad.

Next, the questionnaire is loaded into Claude Code or Codex in the “ask questions—accept answers by voice” mode. We answer all the document’s questions. If we ourselves do not know what to answer, the questionnaire can be sent to the knowledge owner or the product team. In our context, this can be, for example, @d.dolgov: this is even better, because answers come from the primary source rather than being completed by the model.

After the answers, we give the command to create the required document based on the best practice template, the combined database, and answers. Here, combined data means all collected information: source MD files, Confluence, transcriptions, source of truth, secondary documents, answers, and additional clarifications.

If you do not like the resulting document, that is normal. For example, development may look at an ADR and say that the format or composition of the document is unsuitable. In this case, there is no need to start from scratch. You can rewrite the format or composition of the document using the already prepared answers.md from the Narrative Leader or another primary source. Answers are a valuable foundation; they should not be thrown away just because the first version of the final document turned out unsuccessful.

If new information, clarifications, or decisions are added during the rewriting process, a separate artifact or handoff in Markdown must remain for them. This file must be committed to the folder of the given document on GitHub. For example, if it concerns an ADR, such a handoff must be located in the ADR folder. This rule protects us from losing context: any new input must remain in the sources, rather than only dissolving into the final text.

If questions for the product team with clarifications are needed, they can immediately be created as another questionnaire in Markdown. With this approach, answers will be fast because it is easier for people to answer specific questions than to read a large document and look for where clarification is needed themselves.

It is also useful to look into the shared Source of Truth folder, where the most valuable product information is stored. Before creating a new document, you can load into Codex or Claude Code not only current materials but also previous questionnaires and answers. If Source of Truth already contains 80, 120, or 200 questions and answers with maximally accurate firsthand information, this is an enormous context that cannot be ignored.

All documents from Source of Truth are additionally duplicated in Confluence, in the Metas/Metasdev space, and then uploaded into Neuronet and Slack. This can be done manually now; later, such synchronization can be automated. The point is that the Markdown repository becomes an AI-readable source and working base, while Confluence remains the familiar place for people to read and navigate.

If we follow this sequence for several product iterations in a row, we will get a substantial layer of always accessible firsthand product information. This is information without the game of telephone, available to the entire team across all directions. And this is already a very strong result in itself: we are not just writing documents, but building product memory that can be read, expanded, reused, and uploaded into AI.

The main principle: Markdown documents are not made for the sake of Markdown. They are needed to turn conversations, meetings, and fragmented decisions into a shared knowledge layer that people and AI can work with. Codex in this process is a working tool for local product work: it reads the folder, helps structure sources, assemble documents, extract the relevant part of a discussion, and maintain project context.

In this setup, Neuronet becomes a way to distribute already prepared information more broadly: to the company, partners, developers, managers, and everyone who needs to understand what is happening. If we do this process correctly, we reduce the gap between those who conceived the product and those who must later make it, sell it, support it, or explain it.

That is why we work with MD files, Codex, and Neuronet not as a fashionable toy, but as infrastructure for product memory. A conversation disappears on its own. Not everyone will watch Loom on its own. Nobody will read a large AI document on its own. But a well-organized source information layer in Markdown can be read, searched, uploaded into Codex, updated in Neuronet, and used as a living base for product work.