Analytics Requirements Documentation | Community
Skip to main content
J
JennyMu
Level 1
May 28, 2026

Analytics Requirements Documentation

  • May 28, 2026
  • 2 replies
  • 144 views

How are you all documenting your analytics requirements to pass to developers? We release new features/products on our website and app monthly, and are currently using the same drawn-out and tedious process to request our analytics implementation work that we’ve been using for years. We (the analysts using Adobe Analytics) receive designs of the experience in Figma from Product, screenshot those screen by screen and outline what variables/events need to set on each screen/with each interaction in a PPT, and then a technical specifications document gets created by someone on the more technical side (using trackState, etc.) in a PDF. That document is then passed to IT for development. There has to be a more efficient way. I’d love to hear how all of you are handling this process when you’re pushing multiple analytics implementations across multiple platforms monthly.

2 replies

Jennifer_Dungan
Community Advisor and Adobe Champion
Jennifer_DunganCommunity Advisor and Adobe Champion
Community Advisor and Adobe Champion
May 28, 2026

For our org, we have a set of documentation elements.

 

First, I have a Spreadsheet that is shared for the global suite… tabs include a list and description of every dimension and metric in use (the descriptions correlate to the descriptions in Adobe, and also indicate if something is app or web only), I also indicate the expected format, if the dimension is mandatory, and if it exists on page views or interactions, or both.

I also document in this file all our Processing Rules and our Marketing Channel Processing Rules.

 

 

Next, I have very large (500+ page) documents for web and another for mobile app… These are split into “Global” items (tracking that can exist anywhere in the site or app), and Page Specific.

These documents include notes about the implementation, Activity Map Regionalization (we are using data attributes to break our sites into readable regions),  sample data layers (we use a custom data layer), Each page view / action has a table showing the expected output (sample data is bold and dark red to indicate that it could vary based on the page) while “hardcoded” set variables for the page or action are just normal text. 

I have a colour-code system… New things are highlighted in a soft green, changed Items in a soft yellow, and removed items in a soft red…. and Important things in the “highligher yellow”.

 

I have web and app documents separate, because there are some differences in flows/pages, and definitely they are different in how the info is sent (Apps are using context variables that we map with processing rules)… but when working on requirements, I will have both documents open to ensure that both documents match what is being collected.

 

I then have other supplementary documentation, such as our Newsletter UTMs (this is new… we’re finally organizing what we have), and this will fix a lot of out-standing issues that have plagued us for years…. 

 

 

In my case, the Analytics team is small… I am basically in charge of the planning, design, documentation, Launch Implementation for Web, and Processing Rules for Mobile Apps… I work closely with our developers to make sure they know their parts (like Data Layer or Custom Events or Context Variables and Triggers)

 

 

For a lot of our implementations, I won’t start the requirements until we have a mostly working version in Dev… For simple things I can… but features rarely “work” like they are described in the flow/mockups… and I’ve been burned too many times, having to redo requirements cause it didn’t work the way I was told it would work…. 

    J
    JennyMuAuthor
    Level 1
    May 28, 2026

    This is really helpful - thank you for the response! So when you work with the devs, what format are you handing over to them? Is it just an Excel doc with the subset of the relevant items from the master doc? Or do they reference the same master web/app docs and look to your color coding to understand what new/changed items need to be accounted for based on the experience enhancements?

      Jennifer_Dungan
      Community Advisor and Adobe Champion
      Jennifer_DunganCommunity Advisor and Adobe Champion
      Community Advisor and Adobe Champion
      May 28, 2026

      You’re welcome.

       

      We use Jira for all tickets. New features, changes, removals, etc…

       

      So I will usually write up details of the change, highlighting the particulars right in the Jira ticket, then link to the master document will the relevant sections referenced.

       

      The document is organized something like:

       

      1. Global Implementation

             1.1 Global Item 1

             1.2. Global Item 2

                     1.2.1. Sub Global Item 2

                     1.2.2. Sub Global Item 2

      2. Page Specific

             2.1. Page A

                      2.1.1. Regionalization

                      2.1.2. Page Tracking

                      2.1.3. Special Implementation

                               2.1.3.1. Click A

                               2.1.3.2. Click B

                               2.1.3.3. Interaction X

      ….

       

       

      This way, every section is clearly referenced and easy to point to the section (or sections) that are part of the ticket.

      So I will specifically say, “See Section 2.6.1.2” or “See all of Section 2.7”, etc

       

       

      Jira doesn’t allow me to put the details as clearly as my word doc, so I do what I can to impart the needs in the ticket, but leave the details to the master document.. then both Dev and QA will work from the same file.

        Anonymous_badger
        Anonymous_badger
        Level 1
        June 8, 2026

        Hi ​@JennyMu 

        Jennifer's answer covers the documentation structure well: variables, color-coding, and separate web/app docs. Building on that, here's a suggestion to specifically eliminate the Figma-screenshot-PPT-to-PDF complexity you described.

        1. Stop converting Figma to screenshots and link to Figma instead

        In your spec document (or SDR), add a column for "Design reference" that links directly to the Figma frame for that interaction. When the design changes, the link still points to the latest. Although it might require some process adjustments and refinement, once you nail it, it’s set and done. 

         

        1. Separate the data layer specs from the analytics spec

        Maybe I misunderstood, but as I read it, your current process involves one document that serves two audiences: analysts who care about what gets tracked and developers who care about what they need to push. My recommendation is to split this clearly:

        • Data layer specs: what variables/events the data layer or SDK must expose in what format for IT to build against.
        • Analytics spec: what Launch/Tags reads from that data layer and sends to AA. This is what the analytics team owns.

        Keeping these separate means developers get a clear idea of what they have to produce. And when something breaks in QA, you can immediately tell whether the fault is in the data layer (dev's side) or the mapping/rule (analytics side).

        1. For the Jira ticket handoff

        Rather than generating a new PDF per release and sharing via Sharepoint or Email (which can easily fall through the cracks), the Jira ticket becomes the failure-proof medium: a short description of what changed, with row references to the master spec and links to the Figma frames. You can even add the data layer specs directly in the ticket.

        • Dev implements from the data layer specs in the Jira ticket (and remains accountable).
        • QA validates against the same spec rows (Jira ticket recommended here, too).
        • No new documents created per cycle. Plus, you can recycle and evolve specs in the Jira ticket structure for future releases.

        This won't necessarily eliminate setup time, but it reduces per-release overhead significantly once the foundation exists.

        Arturo Rivero
          Jennifer_Dungan
          Community Advisor and Adobe Champion
          Jennifer_DunganCommunity Advisor and Adobe Champion
          Community Advisor and Adobe Champion
          June 9, 2026

          Right, I don’t put explicit layout screenshots in our documentation… I will sometimes put a small sample (not to highlight the specific design, but just as a reference)…

           

          For instance, our Mobile Apps, we track the equivalent URLs in our data (these also correspond to Universal Linking)… but since the URL isn’t visible in the app, I will put a small thumbnail to be sure that everyone knows which page is being referenced… many of those screenshots are technically out of date, but they are enough to identify the page… I make sure to write my requirements with “dynamic” needs (i.e. Region Names for Content Blocks, or how to structure page names based on different sections, etc), and when I need specific values, I will make sure to note those down (like if a block has a user name in it, I will make sure that no PII is captured, but instead a generic block or link name will be recorded)

           

          While Design and Analytics are connected, you will drive yourself crazy trying to make sure every visual change is covered by your documents…  if it’s very important that analytics is tied to specific visuals, maybe you need to add Analytics notes into Figma itself, and then just reference that Figma doc from your document?

            Terms & ConditionsAccessibility statement

            Loading footer...