Topics for consideration of long-term Terminology Engine developments
Over the last days, as an author, I experienced some difficulties in writing terminology-files. To me, it is not clear which of these difficulties should/could be resolved, and which is just something we'll have to deal with (or defer to vsn n of the terminology engine). I created this issue so that I can log the difficulties I run into, and we can discuss what to do with it (if anything), and when.
I think we can live with these issues - at least for now. I can imagine that at some later stage (perhaps even after TEv2) more author-oriented parser/content processors might be constructed for use in a CI/CD pipeline that would resolve this issue, and they might have associated tools (e.g. vscode extensions) that help authors identify and correct any mistakes.
1. Referencing to pictures and documentation files that are not part of the terminology corpus
Currently, authors need to be aware of the underlying software, in our case docusaurus when making such references. Drawbacks include:
- the documentation corpus is not trivially transferrable to other systems (problems may include referring to other documents, or specifics in the markup);
- constraints for writing documents come from multiple sources (that may be independently updated from each other). The implication might be that a parser/generator be developed that more or less replaces docusaurus, at least many of its features, which seems to be an overkill.
2. Docusaurus peculiarities
While I very much like the docusaurus idea of having a header with key-value pairs that can be used for further processing, the body of such files is very much code-writer-oriented. For example, including an image requires the statement import useBaseUrl from '@docusaurus/useBaseUrl';
, allowing the author to subsequently include the image somefile.png
that has been stored in 'static/images/' using HTMLtags:
<img
alt="some alt text"
src={useBaseUrl('images/somefile.png')}
/>
Thinking in terms of our terminology model, it might be beneficial to treat an image in a similar way as a term (they're both semiotic signs, which would imply that they are stored in the location of the scope in which they have been defined.
3. Generator feedback to authors.
I've seen the following happen:
It is hard for (authors like) me to find out what is wrong and how to correct this. Better ways of informing users would be welcome. If the Terminology Engine is to be productized, better support of its users in terms of identifying mistakes and helping them fix it seems a basic requirement.