DITA-OT + Copilot demo
How I replaced the Oxygen XML editor with Copilot
DEMO. ANALYZE. DOCUMENT. REPEAT.
This (short) post describes how I used CPLT (without Oxygen XML) to
setup my mirror (without the bells and whistles) at https://ziptieai.com/436b_dita-ot-docs/out-userguide-professional/index.html
of the DITA-OT docs site https://www.dita-ot.org/dev/ .
TOC
1 My opinions on DITA usage
2 How I Replaced Oxygen (editor with no AI) with Copilot (CPLT)
3 Workflow diagram
4 AI is not yet perfect… but getting there
1 My opinions on DITA usage
Only certain kind of docs require forced structure. I have worked on such projects
Siemens Industy 4.0
Furrion technical specs
Mil-std docs
Doc text reuse does not necessarily mean DITA. I configured a Framemaker single source doc system that created very large user guides for
Multiple customers
3 languages (English, Chinese, and Japanese)
Multiple SW versions
An example output is available at https://github.com/terrytaylorbiz/portfolio?tab=readme-ov-file#21_fgx_ugpdf. This used standard Framemaker (with conditional text and variables) to get the job done with the simplest solution possible.
When DITA is overused, the result is not optimal. Quality end user SW tool docs require a (long) initial period of restructuring and reorganization. The user docs for DITA tools I tested this past week (FM structured/DITA, Oxygen, DITA-OT) are a perfect example.
They use DITA, but don’t need to. Such docs don’t reuse text (or if they do, its easier (and better) to simply copy the text). Its true that DITA helps in certain ways (multi-user, etc) but the added complexity forces the writers to stick to a rigid structure instead of constant improvement. The added complexity invariably lowers the quality of the content (a human can only handle so much complexity). The end result is not optimal.
If you have to use DITA for user guides, then use only AI + DITA-OT. AI LLMs (Copilot) are redefining the dev environment for DITA.
Oxygen does not have AI add-on (it has “Positron assistant”, but I am talking about heavy duty code and debugging assistants). But rather than adding AI to Oxygen, the real solution is using AI instead of Oxygen. This post describes my proof of concept demo.
2 How I Replaced Oxygen (editor with no AI) with Copilot (CPLT)
Can you replace Oxygen with CPLT? For my requirements, for this demo, CPLT was the better choice. This demo is another example of how AI is redefining entire industries.
In this demo I deploy/maintain my clone of the dita-OT doc site. Instead of using the standard Oxygen XML editor that does not have AI for fixing coding errors...
… I used only Copilot (inside of VSC) that is very good at automatically fixing DITA errors!
This is a proof of concept of how LLMs already can replace complex IDE’s.
This drastically simplifies dev.
However, dev is still a challenge, because the pace of dev picks up drastically
(see #436 ch6 CPLT15-25; I really struggled to stay in the pilot’s seat while working with Copilot).
3 Workflow diagram
The diagram below shows the workflow steps for
The DITA-OT site at https://www.dita-ot.org/dev/ (maintained by DITA-OT)
My mirror site at https://ziptieai.com/436b_dita-ot-docs/out-userguide-professional/index.html
Dita-OT team workflow:
Edit the doc source with Oxygen tools
Push to the repo
Github actions publishes the repo
My workflow (see docx #436 for my notes).
4 Clone the repo (ch6)
5 Build (ch6 CPLT15-26). Note that the build only includes the basic content (not Jekyll, etc).
6 Push to Github (ch7) and deploy to Github pages (ch8).
7 Open in the browser https://ziptieai.com/436b_dita-ot-docs/out-userguide-professional/index.html.
8 Edit the repo (add/delete pages, fix links) using only Copilot (not using Oxygen) (ch9)
4 AI is not perfect… but getting there
CPLT reliably fixed errors autonomously in #436. But I was also able to remain in the pilots seat, controlling CPLT.
On the other hand, GPT not only failed, but “locked me out” (#436 ch3 GPT7-10) and just went silent rather than admit defeat.
DEMO. ANALYZE. DOCUMENT. REPEAT.