Global Dictionary for Annotations

[Mr4Goosey]

What's your feature/idea?

Hi all,

We use GitBook to manage public documentation for our Unreal Engine plugin, Voxel Plugin. Within our plugin we have a relatively large amount of new concepts, which Unreal Engine users won't be familiar with. For these concepts, using annotations to provide inline explanations of what we mean with specific terms is incredibly useful.

In our usecase, we're finding that for most of our annotations, we want each usage of a given term to be annotated with the exact same information each time. Right now, we have to manually annotate every single occurrence of a word, which is labour-intensive and incredibly tricky to maintain, as each revision will require us to edit every occurrence.

As an example, we refer to variables within our graph system as uniforms and buffers. This can be confusing to new users, as we use this terminology a lot, but they may not have read the introductory articles. It doesn't make sense to include explanations for this in every article, so the ideal solution is to use an annotation, potentially with a link to an in-depth article on the topic within the annotation.

Realistically, we want the same annotation to appear in (almost) every single instance where we use these terms. As such, a dictionary of terms, defined per space, where each word in the dictionary is automatically annotated, would be incredibly powerful.

What's your desired outcome?

The desired outcome is for us to be able to, per space, define a list of terms with matching annotations, and to then be able to mark a word in a text as being linked to a particular entry in that list of terms, showing the definition in-line.

This could potentially come with automation tools where words in the list are automatically annotated, but for those, we would want to be able to mark certain occurences as exceptions. If we were to use the same term with different meanings in different contexts, we would want to mark it to not be automatically annotated. Additionally, we'd want to be able to manually mark an unrelated word as being annotated with an entry in the list.

What's the impact of this for you?

• Critical
• High
• Medium
• Low

Anything else?

Apologies if I haven't formatted this the way it should have been!

[seanthomasdevlin]

We are using GitBook to migrate all our produce docs from confluence and various github wikis. So far, we are really happy with it.
I had the same wish as Mr4Goosey. With such a large produce suite, we would ideally create annotations 1x and reuse them everywhere a certain term appears. When we compared products, I noticed that Archbee had this and Gitbook not.
So I think this would be a core feature for a CMS for technical documation sites, validated by users and competitors alike

[prathewzhub]

Variables representing a phrase or sentence that may be reused and Snippets representing reusable content (a sentence or paragraphs with images and links if they exist) would be a great value add.
As referred by @seanthomasdevlin, Archbee has the above features.

[seanthomasdevlin]

Any update on this Gitbook? In my humble opinion, the Annotations feature pretty useless without a global implementation. Your competitor has this already for some time.

Also...Ideally, Gitbook could even scan the space and auto-add or recommend replacing plain-text keywords with annotated versions, based on a dictionary.

[Mr4Goosey]

I'll just hop in as well and re-state that I really do still miss this feature quite a bit. Annotations as they are work for some context to be added to a section, but they're impossible to maintain at scale.

[oneiric-oskar]

This is a feature that we also really miss. We link to a glossary page at the moment because annotations aren't maintainable, but leaving the page that you're reading on is not ideal.

Even if the automation part is not implemented, it would still be a great improvement to have some form of list to pick from.

[Mr4Goosey]

That's a very valid point - the core issue here isn't having to annotate things manually, it's that we have to maintain every annotation separately, instead of just being able to point to a set dictionary. At its core, the feature request doesn't require any automation, it just needs to be possible to maintain a global dictionary that can be referenced inline.
Editing the OP accordingly.

[sarahf16]

A list to choose from would save me a lot of time as we have a lot of annotations.

[brunommst]

Hoping to move this request up as well. I've been setting up Gitbook for my company for a few weeks and having a robust global 'Glossary' based on the annotations would be ideal for my writers.

[MikkoSairo]

I would like to raise this up by saying we really wish this was a feature in GitBook. When trying out HelpJuice platform I really fell in love with this feature (automatic annotations/tooltips for terms in articles, which are defined in Glossary) and would love to be able to have it in Gitbook.

It's not even a huge amount of code to add, ten lines of JS and few more for CSS to get the MVP solution, and would have done it myself if not for disallowing the custom code.