docs-site
docs-site copied to clipboard
couchbase
[EXPERIMENT] term-macro
Inspired by the text adventure game language Inform7, and in particular its features for formatting the names of things. http://inform7.com/book/WI_5_3.html
Inform7 is based around objects, and finds clever ways within its (English-like) syntax to describe and name them, and also express relationships between them.
It seems like something a documentation system might want to do, only instead of "The brass lantern is in the chest" we might want to declare that "An Application Service is a kind of Service. It has zero or more Application Endpoints."
Anyway, this macro just looks at the formatting of names for now…
What's the problem that this solves? Is it to enforce consistent terminology? 🤔
Because if that's the case, it seems to me, you then have the problem of enforcing the use of term macros.
What's the problem that this solves?
Good question @simon-dew!
This came up from our N1QL -> SQL++ question. More recently we're trying to name e.g. "App Service" or "Application Service" or "Backend-as-a-Service" and thought it would be convenient to tokenize these so they can all be changed en masse when we get the definitive wording. But that approach has issues.
I'm not sure if the solution is worth shoehorning into existing process, but thought it was interesting enough thought experiment in marking up our "objects" (terms) to share with team.
More recently we're trying to name e.g. "App Service" or "Application Service" or "Backend-as-a-Service" and thought it would be convenient to tokenize these so they can all be changed en masse when we get the definitive wording. But that approach has issues.
Yep, (a) don't I know it, and (b) @RayOffiah rightly pointed out that even if you can completely automate the process of substituting one term for another, and fix all the dependent linguistic issues, there may still be issues of style, tone, or word choice which just can't be automated, so the author is going to have to examine every instance by eye anyway.
But thinking about it, one thing that might still be really useful in this regard is some way of simply marking terms as terms, so that if we do need to find all instances of a term throughout the documentation, we can do so with greater confidence. (But still doing en-masse replacements manually, not programmatically.) I don't know what this markup would look like. I think simple markup is better, to make the barrier for authors as low as possible. Maybe use AsciiDoc's built-in custom inline markup with a term role? I'm also thinking about document portability.
An [.term]#Application Service# is a kind of Service
Does seem a little hard to read though. What do you think?
Maybe use AsciiDoc's built-in custom inline markup with a term role
This might quickly become unworkable if you have a lot of terms in a page.
An [.term]#Application Service# is a kind of Service
Ooo. Yes, that's not beautiful, but portability is worth something. Could try it on one page and see how it looks.