search

briandominick / codewriting

Source for Codewriting (book) and the Codewriting/Code the Docs (site/blog)
Other
50 stars 13 forks source link

Semantic Structure #33

Open lief-erickson opened 6 years ago

lief-erickson commented 6 years ago

Figure 3. Semantic structure in Oxygen XML Editor (Source: oxygenxml.com (c) SyncRO Soft SR, republished under Fair Use)

While true that is what the oXygenXML interface can look like I don't think anyone uses that UI very much or for very long. I know I certainly never used it beyond the first couple of days (if that). I frequently switch between Author and Text modes in oXygenXML. It depends on what I'm trying to accomplish. But I never had the semantic tags showing when I was in Author mode. So, I feel it's an unfair comparison, especially since the oXygenXML documentation states that the syntax highlighting is to "reduce the time it takes to internalize the semantics of the structured content." The same could be said about the editor for any tag-based language.

But I don't think the heavy tags-exposed UI is what experienced contributors would use. For casual contributors there are WYSIWYM ways to contribute content (including through a browser without having to install any software) without showing the heavy markup. For casual contributors to tag-based content, it may need to go through a reviewer who is familiar with the required (or preferred) markup -- just like a part of any code review where developers have to adhere to specific coding standards. Perhaps this review and contribution process is not as fast as a lightweight markup language as AsciiDoc or rST, but it's still faster than many alternatives, such as having the developer (or whoever the contributor is) talk at a tech writer. As such, some teams may accept the trade-off.

briandominick commented 6 years ago

Good points all. I have never used Oxygen except for non-content XML work years ago. I wonder if you have any DITA/XML editors, WYSIWYM or otherwise, that would give me a better taste. I actually think the semantic highlighting is kind of nice and wish it were an option, so I'm glad it can be toggled.

I definitely want this part -- or anywhere that DITA/XML is discussed -- to not be a matter of biasing writers against the tools. My main purpose here is to make the case that devs will already be biased against the tools, so that's a barrier to most DITA/XML approaches.