Adding owner/contributor author metadata to DITA topic files

Post by **chrispitude** » Wed Feb 03, 2021 2:59 am

Hi everyone,

We plan to start storing author (owner/contributor) metadata in our DITA topic files:

<topic id="xyz">
  <title>My Topic</title>
  <prolog>
    <author type="owner">chrispy</author>
    <author type="contributor">milada</author>
  </prolog>
  ...
</topic>

I created a refactoring operation to help set the metadata in existing content:

image.png

Here are the files if you want to use it:

add-author-v1.zip

The refactoring operation creates a <prolog> if it doesn't exist, and updates it in-place if it does.

The refactoring operation offers two roles (owner and contributor) but you can edit the value list in the .xml file to add as many role values as you want. If there are multiple authors and multiple roles, the <author> elements are sorted by role first (according to the order list in the .xsl file), then by username within the same role.

There are some limitations to this refactoring operation:

It only works on topics that have a <body> element.
It does not work on glossary files.
There is no removal operation.

Cosmin Duna · Post by **Cosmin Duna** » Wed Feb 03, 2021 4:00 pm

Hi Chris,

You did a great job here. Thank you for sharing it with us!
I added an internal issue(EXM-47307) to analyze if we will add a refactoring action like this in Oxygen.

Regards,
Cosmin

Post by **chrispitude** » Wed Feb 03, 2021 4:46 pm

Thanks Cosmin!

There are two reasons we think topic-level author metadata will be useful.

The first is to help automated scripts send an email. For example, we might have a nightly script that does some kind of validation check. If an issue is detected in a topic file, the script can directly email the relevant writers, even in complicated situations like multi-writer books, reused content from warehouse directories, etc.

The second is to help the humans determine who to contact with questions. For example, a writer might want to make a fix or improvement suggestion for a topic file. With this metadata, the writer can quickly send an email to the right person without too much work.

(An exciting future possibility is to allow feedback from external users to get routed directly to the content owners.)

Post by **chrispitude** » Wed Apr 07, 2021 4:21 pm

There was a bug with the previous script where non-<author> elements in existing <prolog> elements was discarded instead of preserved. I'm attaching an update that fixes this bug.

add-author-v2.zip

I plan to extend this to maps and bookmaps soon. At that point, I will provide that version in an Oxygen XML Blog post (at https://blog.oxygenxml.com/) instead of in a forum message. Providing the refactoring operation in a blog post will allow me to update the post instead of posting repeated attachments here.

Cosmin Duna · Post by **Cosmin Duna** » Thu Apr 08, 2021 10:45 am

Thanks Chris!
I updated our internal issue with the last archive you provided.
It's a good idea to post it on the Oxygen XML blog. These are some steps you have to follow to add the article:
https://blog.oxygenxml.com/topics/welco ... nr_rr3_jkb
If you have any issues posting it, feel free to contact us for help.

Regards,
Cosmin

Adding owner/contributor author metadata to DITA topic files

Adding owner/contributor author metadata to DITA topic files

Re: Adding owner/contributor author metadata to DITA topic files

Re: Adding owner/contributor author metadata to DITA topic files

Re: Adding owner/contributor author metadata to DITA topic files

Re: Adding owner/contributor author metadata to DITA topic files