Improve the documentation about adding and deleting tags

I had to search the forum. As far back as 2011 and going forward, the help on deleting tags points to a section in the Documentation that says below, where I have emphasized the one sentence.

Applying tags: When you apply a tag to an item, a replicant of that item is created in the Tags section for the current database. For each tag you apply, you will have a replicant in each tag group. These are not the original items, but only instances of the items. If you delete a tag group, the group and the replicants it contains are removed. The original items in the database remain intact.

Please please please (please) … improve/expand the documentation about adding and removing tags. Clear out the (exceptionally hard to parse) passive and “double-speak” language and write a specific subsection about deleting tags. As a recommendation …


Applying tags: When you apply a tag to an item, DevonThink creates a replicant of that item in the *Tags* section for the current database. As discussed elsewhere(hyperlink), replicates are not the original items, nor are they duplicates; replicates are only instances of the items as a way to reference directly to an item without duplicating (copying) it. You will be able to jump or go to the original item that has been tagged by clicking on the replicate in the *Tags* section.

Deleting tags: If you delete a tag in the *Tags* section of a database, DevonThink removes the tag and its replicates from the *Tags* section. DevonThink also removes the tag that you delete in the *Tags* section from the original item or items, but all original items that were referenced by the tag that you delete remain in the database. Deleting a tag in the *Tags* section of any database is therefore the same action as removing a tag directly from all source items that have that tag but not removing the source items themselves.


My brain will thank you greatly.


JJW

4 Likes

It seems kind of self-explanatory. If you delete a tag you’re not deleting the document. No?

3 Likes

Personally, I ignored the whole tag special-replicant thing
My brain can easily handle adding and deleting tags

I once had a problem deleting records when I happened to be in the tag view
The records appeared to be deleted, but only the special-replicant was deleted

2 Likes

I can say honestly I never even read the documentation on it and didn’t know it was even a thing. I’ve just tagged documents if I wanted to and never worried about deleting those tags, as it would seem common sense that removing a tag doesn’t mean I’m removing a document. Perhaps that’s just me.

3 Likes

For telling the truth, the documentation about tags was a bit confusing for me, too. I appreciate the suggestion of DrJJWMac as it is very clear and leave no room for doubts.

1 Like

Writing documentation is difficult. Make it too terse, and people will complain that they don’t understand. Make it too verbose, and people will stop reading it or get confused because the same thing is said several times with different words.

As in this suggested improvement, which I don’t think is one:

It removes them. They’re gone. Consequently, they don’t exist any longer. Adding “from the Tags section” is not helpful, as that implies they might still exist elsewhere. Which they dont.

Which begs the question what an “original item” is – I doubt that it refers to the originality of the content, so what does “original” mean here? Personally, I don’t think of a tag “referencing a document”, but rather of a tag being “attached” to a document. That concept translates to “the tags are removed from all documents they’re attached to”, avoiding the complicated grammar with two "that"s.

That’s overly verbose (“the same action” instead of “the same”, “of any database” is not helpful – if it’s any, there’s no need to mention databases at all), the sentence is far too long, it introduces weird terms (“source item” – is that the same as an “original document”? But why “source” then – no document is the “source” of a tag).

One would have to read through a lot of stuff to understand a simple concept:

If you delete a tag, it is removed from the database and from all documents it was attached to. Those documents remain otherwise untouched.

1 Like

What might be self-explanatory to some is not explained well enough for me to appreciate. Especially with the overlap of passive voice and references to replicants and tags versus tag groups (and “these” what??? these tags? these tag groups? these replicants?).

Perhaps simpler …

Applying tags: When you apply a tag to an item, DevonThink creates a replicant of that item in the *Tags* section for the current database. Clicking on the replicant takes you to the item itself. Replicants(hyperlink) are discussed elsewhere in detail.

Deleting tags: When you delete a tag in the *Tags* section for the current database, the tag is removed from the database and from all items where it was attached. The replicants that were associated with tag are also removed from the database, but their referenced items remain otherwise untouched in the database.


JJW

1 Like

I agree that passive voice is not good, as it tends to obscure the acting agent. And also that the current wording is too complex. Especially as it uses “replicant” and “original item”, whereas elsewhere we’re told that a “replicant” doesn’t have an “original item” but they’re all one and the same. Not to mention the horrific adverb “proactively” (which, I humbly suggest, means nothing but “actively”. At least outside of marketing circles).

In place of “replicants”, I’d suggest using “reference” or “pointer to”. Anything but “replicant”, since that’s something else: I have a lot of tagged items whose number of replicants is 0 – how can that be if the “thing” in the tags group is a replicant?

3 Likes

Some time ago, I had to contact Support to ask if it was safe to remove a bunch of garbage tags that had been accidentally created during import. I did RTFM first, and it wasn’t at all clear that removing the tags did not remove the items themselves. (Part of this lack of clarity was the fault of the UI, as well.) All of this is a way of saying that I fully support any effort to clarify the documentation. :slight_smile:

2 Likes

Agree. I think this situation would be a lot more clear if replicants in Tag Groups were marked in the “replicant” color (assuming that “Preferences > General > Appearance > Mark duplicates and replicants in color” is enabled).

There is an aspect that I found about recently, related to tags, that is very confusing.

The documentation and the team say that when we add a tag to an item, it creates a replicant.
But this isn’t true.
The behaviour is different depending on whether we’re talking about an ordinary tag or a group tag:

  • If it’s a group tag, the Instances dropdown in the Generic Inspector of that item will indicate that there are multiple replicants and allow the user to navigate between them.
  • But if it’s an ordinary tag, this does not happen! It will still say “0 replicants”. And this makes sense.

The term “replicant” is being used for two distinct situations. Why?
This makes it very confusing for the user(s).

When I observed this, I searched this forum and found the Tags, Deleting, Replicants? thread from another user (@romebot) that also had the same confusion regarding tag deletion and replicants.
I also pointed out this issue of the overloaded usage of the term “replicants” in that thread (here and here).

I can understand that, perhaps in the DEVONthink source code, the implementation is similar for ordinary tags and non-group tags, and that the team is used to employ the term “replicants” for both situations.
But from the perspective of the user, it’s not the same thing, and describing it as if it is the same thing makes it very confusing.
Ordinary tags are simply applied to items, and there’s nothing in DEVONthink indicating that replicants are created when we apply ordinary tags. This only happens with group tags, because they are akin to folders, and therefore, the term “replicants” makes sense.

Therefore, it would be very beneficial if the term stopped being applied to ordinary tags.

2 Likes

Very good point. That’s why I suggested to limit the usage of “replicant” to those cases where the UI clearly shows replicants (color & number of replicants > 0). For documents referenced by normal tags, something like “reference” or “pointer” would be better, imo.

1 Like

This is being looked at internally. Thanks.

2 Likes