How do you document why a Jira field exists before everyone forgets?

One small admin problem I keep running into in sandbox notes is that Jira fields often outlive the original reason they were created.

The field name may still make sense, but six months later it is harder to answer:

- who asked for it

- which workflow/report depends on it

- whether it is still used

- whether it is safe to hide or remove

I have started liking a simple field note pattern:

- purpose

- owner/team

- where it appears

- reports/automations that depend on it

- review date

Do you document field purpose anywhere, or do you rely mostly on naming conventions and cleanup sessions?

8 comments

Comment

I always add a description when creating a new custom field that explains its purpose along with the Jira work item key where the field was requested. This helps me quickly understand what the field is for and gives me a way to trace back to the original request if I need more details such as who requested it.

I realize this approach won't work for everyone since some companies archive work items after a certain period of time. That's not an issue for us though as we never archive work items to meet our time tracking requirements.

Also just to note, where I work right now there really isn't a huge amount of custom field requests, everyone is really good about seeing what could work first before we go out and create something new.

Like • like this

We don't add fields unless they are required for a Service ticket that requests/needs it so the documentation of when, why, what is contained in that ticket.

It's a bit of effort to find those tickets should the need arise of course but that need is relatively rare.

Like • like this

We also use a readable name and useful description, but creating an Assets schema to track with those fields would allow you to use automation for review and report from it when needed.

Like • like this

@Jared T_ Finnegan , Welcome to the Community! This is an interesting idea, have you implemented this yet? Just wondering how time-consuming it would be to use this method, we're a very small shop of admins but this sounds handy.

Like • like this

We have. Our lead here is very Assets happy and we have everything is there. We have been using it since it was Insight. We have customers, products, pretty much everything. It's a full CMDB for us.

When we first started setting up the schemas was simple but getting the business requirements for reporting always takes time. If you are in cloud the automation engine is much better than data center so setting up those to trigger issues for 90-day audits was easy. That keep us current and we create those issues to a project with a workflow with approvals so once the sponsor approves the automation updates Assets.

Like • like this

Nice! Thanks for the info.

Like • Anwesha Pan likes this

I have a Confluence parent page named "Custom Fields." Each child page represents one field. I create a new page with Rovo and give it the prompt: "Write a concise page documenting the details of field customfield_XXXXX."

Rovo creates a page with lots of information that includes a stab at the purpose of the field -- and it's mostly been pretty good.

I have Claude connected via MCP now, so I might switch over to using it, or at least try it out and see if it is any better than Rovo.

Like • like this

We add information in the description on the custom field, and additionally, we have a Jira data dictionary my support team maintains as a SharePoint list which details the field name, which issue types it is used on, the field type, if it is a required field, the purpose of the field, an example of what the data entry should be, and a general tip if needed related to the field.

We also follow a process on a select field, if we disable an entry, we update the name to have a Z and then a space in front of the previous option. That way we can sort alphabetically, and see the entries disabled at the bottom of the list. It is also a good indicator when looking at items, if an entry was disabled.

Finally, as a Jira enhancement, it would be great if there was a way to archive fields no longer being used, vs. the options of being active or deleted.

Like • like this

I don't use the sandbox, but for PROD I use basic change management. I always create a Jira ticket in our designated project. For more robust requests like setting up a new project with the new fields, I also create a Technical Requirements Document.

The custom fields dashboard gives you the DATE LAST USED, and you can add fields to the view.

Sometimes fields are also created as part of ADD ONs installations, unbeknownst to the admin, so your diligence to manage them may not always work out.