January 28, 2026 at 12:00 am
Comments posted to this topic are about the item More Documentation is Needed
January 28, 2026 at 12:25 pm
I've worked on an AI project that uses documents from different companies covering what is, in theory, the same business process. The idea is for the middleman company to be able to advise on which service provider company is most appropriate for the customer.
Those documents take different approaches to information layout and content. If these were a database schema then would resemble random, badly assembled data models no obvious standards.
AI does its best to extract the relevant information from these documents, but even the experts debate the interpretation of some of the source documents.
I am convinced that companies need to think of AI as a 1st class consumer of their content. AI becomes a useful middleman for promoting your content to a wider audience. The higher the quality that goes in, the more likely you will be satisfied with the output and the impact of that output.
A skilled technical writer will structure information and content for easier absorption of information. Someone in an editorial role will improve content. The author's words will be pruned and tweaked so the intended message stands out.
I believe that the disciplines that will allow AI to flourish are information architecture, librarianship and those of editorial QA.
If you make it easy for AI to consume content/information, you also make it easier for people to consume content/information. This is a win/win.
January 28, 2026 at 6:56 pm
I've heard a few people say that docs for code should be structured more for AI/automation/agents than humans. Or it should be in both formats. Not sure what makes it more AI easily consumed, but I do think this will be more important to getting better results from AI
January 29, 2026 at 1:45 am
I've heard a few people say that docs for code should be structured more for AI/automation/agents than humans. Or it should be in both formats. Not sure what makes it more AI easily consumed, but I do think this will be more important to getting better results from AI
Good night, are you serious? Document for humans isn't important, at least to some people? Oh, WOW.
Rod
January 29, 2026 at 3:26 pm
More important ~= Not important. You're taking a leap
January 29, 2026 at 5:17 pm
Heh, it's bad enough getting people (myself included!) to keep documentation up-to-date, imaging managers' frustration (and the workers) trying to keep two different formats (human-readable / automation-agent-AI) of the same documentation current...
As for differences between them, I could see the automation documentation perhaps being more "code-like" so the automation agent could follow along and do what needs to be done, almost some sort of BASIC "program" for it to follow, whereas human documentation would have some explanations ("we do it this way because the specialized software won't work if we do it this other way that sounds better") and be more "story-like" in format.
January 29, 2026 at 6:49 pm
I don't see there being a human version and an AI version. I see it as a unified version.
At present, AI is cheap to consume. At some point soon, the investors in AI are going to want their pound of flesh. Prices will have to rise, and at that point, people will take a good, hard look at the running costs of their AI facilities. I've had conversations with execs who have said that AI increases revenue, but if its cost were to rise much, smaller consumers would not be able to afford the benefits it offers.
Anything that increases the effectiveness of AI, such as improving the quality of its input, will increase the profitability of its output.
So many of the hopes industry has had for new data technologies have crashed on the rocks of poor data quality. Do we really think AI won't be susceptible to the same problem?
I was going to post a link to some research done on AI poisoning. The gist was that experiments have been done where an AI information source was deliberately poisoned with a small number of documents. The experimenters expected the ultimate effect to be minimal. The reality was that it had a much higher impact. The effect was akin to biological amplification observed when DDT was 1st used.
Insects killed by DDT were eaten by small birds and mammals. Those in turn were eaten by larger birds, reptiles and mammals and in turn still larger animals. The concentrations of DDT in the larger animals was high enough to have severe consequences, particularly in egg laying species.
January 29, 2026 at 7:19 pm
Heh, it's bad enough getting people (myself included!) to keep documentation up-to-date, imaging managers' frustration (and the workers) trying to keep two different formats (human-readable / automation-agent-AI) of the same documentation current...
As for differences between them, I could see the automation documentation perhaps being more "code-like" so the automation agent could follow along and do what needs to be done, almost some sort of BASIC "program" for it to follow, whereas human documentation would have some explanations ("we do it this way because the specialized software won't work if we do it this other way that sounds better") and be more "story-like" in format.
The AI can help you with this. It's a perfect task for an agent to look at code changes an adjust docs (in any/all formats). It's a tedious, mundane, well scoped and defined task. Exactly what AIs are good at.
January 30, 2026 at 4:16 am
I think it would be interesting if you input a requirements document, naming standards and a database, if an AI could generate the extended property MS_DESCRIPTION script to describe most of the tables and columns? That is assuming you have a requirements document and naming standards. Conversely, if you have a database with extended property MS_DESCRIPTION defined for all tables and columns, if an AI could generate the requirements and standards document. I think documentation by a human is going to be very critical for an AI to understand a database, propose improvements to naming standards and make good recommendations on how to change databases to included enhancements or bug fixes.
January 30, 2026 at 7:21 pm
Agreed. I wish MSSQL supported the COMMENT ON clause in SQL, but extended properties work, and will be needed for better AI responses (and really, for better human code)
Viewing 10 posts - 1 through 10 (of 10 total)
You must be logged in to reply to this topic. Login to reply