Analyse a new article
Paste a Zendesk article URL into the Google Sheet to queue it for analysis. The tool runs automatically and updates this dashboard every 4 hours.
1. Open the article in Zendesk and copy the URL
2. Click the button above to open the Google Sheet
3. Paste the URL in column A of a new row
4. Leave column C blank — the analysis runs automatically
Target: Grade 12 or below
Content should be readable for anyone at leaving cert level and above. Average score: 12.0
This content significantly exceeds the Grade 12 target and needs immediate revision. Here are 3 specific suggestions:
1. Break down dense technical strings into explanatory text: The article jumps straight into code without context. Before "CREATE OR REPLACE NETWORK RULE datavant_network_rule VALUE_LIST = ('auth.datavant.com'...", add: "You need to create a network rule. This rule tells Snowflake which Datavant servers it can connect to. Run this command:"
2. Add plain language explanations between steps: Between Step 2 and Step 3, add: "Now you need to tell your application about the integration you just created. This links the network access rules to your application." This reduces the cognitive load of processing pure technical syntax.
3. Expand the overview section: Replace "This article includes two step-by-step examples to guide you through initial setup and multi-environment configuration in Snowflake" with shorter, clearer sentences: "This article shows you how to set up Datavant in Snowflake. You will learn two things. First, how to set up the application for the first time. Second, how to set it up across multiple environments."
Plain Language: Needs Attention
- "external access integration" appears without definition
- "PERSISTENT" parameter unexplained
- No context provided for what "register_reference" does
Sentence Length: Pass
Most sentences are appropriately short, though some technical command explanations could benefit from additional context sentences.
Jargon: Needs Attention
Unexplained technical terms found:
- external access integration
- network rule
- secret
- PERSISTENT
- code_schema
- SYSTEM$REFERENCE
- endpoint integration
Active Voice: Needs Attention
Passive constructions found:
- "This must be run in your Snowflake account" (passive - change to "Run this in your Snowflake account")
- "This must be run in your Snowflake account, not in the application" (could be "Run this command in your Snowflake account, not in the application")
Heading Clarity: Needs Attention
- "Setup for Multiple Environments" section has two "Step 1" entries (Development and QA both labeled Step 1)
- Headings don't explain the "why" - consider "Step 1: Allow Snowflake to connect to Datavant (Create external access integration)"
Link Text: Pass
No links present in the provided text.
Abbreviations: Needs Attention
- "QA" - should be written as "QA (Quality Assurance)" on first use
- "API" in credentials context - should be "API (Application Programming Interface)"
Overall WCAG Writing Score: Needs Significant Work
This content scores well above the Grade 12 target and needs significant revision to improve readability:
1. Add transitional sentences between code blocks: The article currently jumps between headings and code with minimal explanation. For example, after "Step 1. Register all tables in a schema", add a plain English sentence like: "Use the following code to register all tables at once." This would lower the average syllables per word by balancing technical terms with simpler connective text.
2. Break down the technical procedure into explanatory prose: Instead of just "CALL code_schema.register_reference('input_references', 'add'...", precede it with: "This command adds multiple table references to your schema. Each SYSTEM$REFERENCE line points to a different table in the raw data folder." Adding context sentences with common words reduces the overall complexity.
3. Complete the incomplete code examples: Steps 1 and 2 under "Update References" show empty parentheses "( )" and incomplete syntax. Complete these examples and add 1-2 sentences explaining what parameters to include and why, using simpler vocabulary to balance the technical terms.
Plain Language: Needs Attention - Heavy use of unexplained technical syntax (SYSTEM$REFERENCE, code_schema.register_reference) without plain English explanations of what these commands accomplish.
Sentence Length: Pass - Sentences are very short, though this may be contributing to the high FK score due to lack of connecting text with simpler words.
Jargon: Needs Attention - Multiple unexplained technical terms:
- "register_reference"
- "input_references"
- "SYSTEM$REFERENCE"
- "persistent"
- "code_schema"
Active Voice: Needs Attention - Primarily imperative commands without clear subject-action structure. Example: "Register all tables in a schema" could be "You will register all tables in a schema by running the following command."
Heading Clarity: Needs Attention - Headings are clear but lack context. "Update References" doesn't explain why or when you'd update them.
Link Text: Cannot Assess - No links present in cleaned text.
Abbreviations: Pass - No abbreviations requiring expansion found.
Overall WCAG Writing Score: Needs Significant Work
This content exceeds the Grade 12 target and needs immediate revision. The primary issue is extremely long sentences averaging 44.6 words each.
1. Break up extremely long sentences: The article contains sentences that run on with multiple data points strung together. For example, the benchmark results should be broken into separate sentences or reformatted as a proper table with column headers and row labels, rather than presenting all data in continuous prose.
2. Add transitional sentences: Insert short, simple sentences between data sections such as "The CLI performs faster on macOS." or "Windows 10 shows different performance patterns." This will dramatically lower the average sentence length.
3. Convert data to structured formats: The benchmark data should be presented in a properly formatted table with clear headers (Operation Type, Record Count, CLI Performance, Desktop Performance) rather than as running text. This removes data from the readability calculation and makes information scannable.
Plain Language: Needs Attention - Terms like "DeID," "tokens," and "records per second" appear without context or explanation for readers unfamiliar with Datavant terminology.
Sentence Length: FAIL - With an average of 44.6 words per sentence, this dramatically exceeds the 25-word guideline. All five sentences are likely over the limit, creating significant comprehension barriers.
Jargon: Needs Attention
- "DeID" - unexplained abbreviation/term
- "tokens" - technical term without definition
- "CLI" - explained on first use (good) but technical
- "Link" - unclear if this is a process name or action
Active Voice: Cannot assess - The text is primarily data-driven benchmark results rather than instructional prose, making active/passive voice analysis not applicable to most content.
Heading Clarity: Needs Attention - The article appears to lack structural headings to separate macOS vs Windows results, or to distinguish between DeID and Link operations.
Link Text: Cannot assess - No link text present in the provided prose.
Abbreviations: Needs Attention
- "CLI" - defined as "Command Line Interface" ✓
- "DeID" - not defined ✗
- "v3.6.0" - version number, acceptable in technical docs ✓
- "M" and "k" (for million/thousand) - common notation but could be spelled out for clarity
Overall WCAG Writing Score: Needs Significant Work
This content is 5.7 grade levels above the recommended target and needs simplification. Here are three specific suggestions:
1. Break up extremely long sentences - The article contains sentences averaging 30.9 words. Example to revise:
- CURRENT: "The User Management page controls which individuals can access your company's Datavant Connect account and tokenization software. Depending on your level of permissions, you can view, add, or delete users, modify user permissions, and/or grant application credentials to users."
- IMPROVED: "The User Management page controls who can access your company's Datavant Connect account. You can view, add, or delete users. You can also modify permissions and grant credentials. What you can do depends on your permission level."
2. Simplify complex procedural chains - Break multi-step instructions into clearer, shorter segments:
- CURRENT: "At the top right corner of the page, click Invite Users Enter the email address of the new user. Adjust the permission for the new user At the bottom right corner of the page, click Invite User"
- IMPROVED: Number each step separately with one action per sentence.
3. Reduce nested conditional information - Statements like "Application DownloadThis permission requires 'Applications Pages' to be ON. Ability to download Datavant's software executables for tokenizing data and creating/linking patient tokens on the Download page" should be split into prerequisite information and action description.
Plain Language: Needs Attention
- "provisioned Admin access" (use "given Admin access")
- "software executables" (use "software programs")
- "inbound shares" (use "shared data you receive")
Sentence Length: FAIL - Multiple violations
- Average of 30.9 words per sentence exceeds the 25-word guideline
- Example: "Only Admins can invite or remove users and modify permissions. If you are not an Admin, reach out to your company Admin to change your permissions or to be provisioned Admin access." (33 words combined)
- The permissions list contains numerous run-on explanations
Jargon: Needs Attention
- "tokenization software" (unexplained)
- "application credentials" (unexplained)
- "software executables" (unexplained)
- "patient tokens" (unexplained)
- "profiling and overlaps" (unexplained in this context)
- "segments" (unexplained in data context)
Active Voice: Needs Attention
- "Invited Users will receive an email" (passive - use "We will email invited users")
- "Permissions will be turned on/off" (passive - use "You will turn permissions on or off")
- "This must first be enabled by Datavant" (passive - use "Datavant must enable this first")
Heading Clarity: Needs Attention
- Missing heading structure in the article text provided
- Procedural sections appear to lack clear headings (e.g., "Invite a New User" vs implied section)
- Permission list needs hierarchical organization with descriptive headings
Link Text: Cannot Assess
- No link text present in cleaned prose to evaluate
Abbreviations: PASS
- No unexplained abbreviations found
Overall WCAG Writing Score: Needs Significant Work
This content exceeds the Grade 12 target and needs simplification. Here are 3 specific suggestions:
1. Break down long, compound sentences: The sentence "It contains relevant contextual information, limitations & conditions, and a breakdown of our analysis by risk type" is part of a longer passage with multiple embedded clauses. Break this into shorter, standalone sentences. For example: "The report documents the risk assessment. It includes contextual information and our analysis by risk type."
2. Simplify dense technical passages: The text "An analysis is conducted to compare individuals in the dataset with groups in the US population that share their demographic profile. If very few patients in the dataset belong to small groups in the US population (see diagram below), the dataset poses a 'very small' risk of re-identification" uses complex subordinate clauses. Rewrite as: "We compare individuals in your dataset to US population groups. We look at demographic profiles. If few patients match small population groups, re-identification risk is very small."
3. Restructure the nested list content: The "Category" section contains deeply nested explanations ("Action - risk was seen in the data and must be modified"). Use simpler formatting with bullet points and shorter definitions. Example: "Category types: Action = modify the data because we found risk. Maintain = no current risk, but watch this variable."
Plain Language: Needs Attention - Contains complex phrases like "facilitate any changes in language which may be desired," "multi-functional spreadsheet," and "pertains." Simpler alternatives: "allow you to request changes," "spreadsheet with multiple uses," and "relates to."
Sentence Length: Needs Attention - Multiple sentences exceed 25 words:
- "Upon completion of an Expert Determination, we will provide a package containing multiple documents which are designed to make the report more digestible, the findings more concise, and the remediations easier to implement." (31 words)
- "It contains relevant contextual information, limitations & conditions, and a breakdown of our analysis by risk type." (17 words but part of complex paragraph structure)
- "An analysis is conducted to compare individuals in the dataset with groups in the US population that share their demographic profile." (22 words)
Jargon: Needs Attention - Unexplained technical terms include:
- "Expert Determination" (used in title but not defined until later)
- "HIPAA de-identification standard" (no explanation)
- "remediations" (used repeatedly without definition)
- "code set variable" (undefined)
- "conditional remediations" (undefined)
Active Voice: Needs Attention - Multiple passive constructions found:
- "was updated to clarify" → "we updated to clarify"
- "are designed to make" → "help you digest"
- "are listed" → "we list"
- "is conducted" → "we conduct"
- "will be provided" (appears twice) → "we will provide"
- "is referenced" → "we reference"
- "are given" → "we give"
Heading Clarity: Needs Attention - "Report Supplement" is vague. Consider "Report Supplement Spreadsheet" or "Implementation Guide Spreadsheet." The heading "Required Remediations" appears mid-text without proper formatting hierarchy.
Link Text: Unable to assess - No links present in the cleaned text provided.
Abbreviations: Needs Attention - "HIPAA" appears without first spelling out "Health Insurance Portability and Accountability Act." The "&" HTML entity should be rendered as "and" or "&".
Overall WCAG Writing Score: Needs Significant Work
This content exceeds the Grade 12 target and needs improvement. Here are three specific suggestions:
1. Break down complex technical instructions into shorter, clearer sentences
- Current: "This article includes five step-by-step examples demonstrating core and advanced tokenization patterns in Snowflake, from simple implementations to filtered, incremental, and batch workflows."
- Suggested: "This article shows five examples. You will learn how to tokenize data in Snowflake. The examples cover simple, filtered, incremental, and batch workflows."
2. Add explanatory context before technical steps
- Current: "CALL code_schema.register_reference('input_references', 'add', SYSTEM$REFERENCE('table', 'db.schema.standardized_names', 'persistent', 'select'));"
- Suggested: Add a brief explanation like: "This command registers your input table with the system. Use this code: [command]"
3. Simplify section descriptions with plain language
- Current: "Tokenize Filtered Data using a View - Useful for processing only specific subsets of data."
- Suggested: "Tokenize Filtered Data using a View - Use this method when you need to tokenize only some of your data, not all of it."
FK RECOMMENDATIONS (continued):
4. Replace complex multi-clause sentences with simple statements
- Current: "Use this when names are already standardized or when you want to preserve exact name formatting."
- Suggested: "Use this method in two cases: Your names are already standardized. You want to keep the exact name format."
Plain Language: Needs Attention
- Phrases like "core and advanced tokenization patterns" and "skip_name_preprocessing" lack plain language explanations
- "Register the input table" assumes prior knowledge without context
- "RESULT_SCAN(LAST_QUERY_ID())" appears without explanation of what it does
Sentence Length: Pass
- Most sentences are appropriately short
- The opening sentence (31 words) slightly exceeds the 25-word guideline but is borderline acceptable
Jargon: Needs Attention
Unexplained technical terms found:
- "tokenization" (used throughout but never defined)
- "preprocessing"
- "persistent"
- "SYSTEM$REFERENCE"
- "RESULT_SCAN"
- "LAST_QUERY_ID()"
- "incremental tokenization"
Active Voice: Pass
- Most instructions use active voice and imperative commands
- Code examples are appropriately direct
Heading Clarity: Needs Attention
- Headings are descriptive but assume knowledge (e.g., "Tokenize without Name Preprocessing")
- Consider adding brief purpose statements: "Tokenize without Name Preprocessing (When to Use This Method)"
Link Text: Cannot assess
- No link text present in the cleaned prose provided
Abbreviations: Pass
- "SQL" and "AS" are standard database conventions
- No problematic unexplained abbreviations
Overall WCAG Writing Score: Needs Attention
The primary issues are: undefined technical jargon, lack of context for complex procedures, and insufficient plain language explanations. Adding a glossary section or inline definitions for key terms like "tokenization," "preprocessing," and "incremental processing" would significantly improve accessibility.
This content exceeds the Grade 12 target and needs simplification. Here are 3 specific suggestions:
1. Break down dense technical fragments into complete sentences
- Current: "'input_references', 'external_access_reference', or 'consumer_secret' 'add' or 'remove' (This is case sensitive)"
- Suggested: "You can register input_references, external_access_reference, or consumer_secret. Use 'add' to register or 'remove' to unregister. Note: These values are case sensitive."
2. Add explanatory context to function descriptions
- Current: "get_configurationReturns configuration JSON for reference types."
- Suggested: "Use get_configuration to retrieve your configuration settings. This function returns configuration data in JSON format for reference types."
3. Explain technical concepts before using them
- Current: "transformRe-encrypts tokens between different encryption keys for secure exchange."
- Suggested: "The transform function allows you to share tokens securely with partners. It re-encrypts tokens using different encryption keys so data can be exchanged safely between sites."
Plain Language: Needs Attention
- Multiple incomplete sentences and fragments: "Site encryption key name Configuration name from Datavant portal BOOLEAN DEFAULT False"
- Missing articles and connectors throughout
- Terms like "EAI registration" used without explanation
Sentence Length: Pass
- Most sentences are brief, with average of 8.3 words per sentence
Jargon: Needs Attention
- Unexplained terms: "EAI registration", "PII data", "de-identified tokens", "name preprocessing", "RESULT_SCAN", "LAST_QUERY_ID"
- "Telemetry configuration status" - no context provided
- "Reference types" - undefined
Active Voice: Needs Attention
- Passive constructions found: "Checks telemetry configuration status" (unclear who checks)
- Many fragments lack proper subject-verb structure entirely
Heading Clarity: Needs Attention
- "Quick Reference Card" section lacks introductory explanation
- No headings differentiate between Commands section items
- Missing hierarchy for tokenization vs. transform commands
Link Text: Cannot assess
- No links present in cleaned prose text
Abbreviations: Needs Attention
- "PII" - not defined (Personally Identifiable Information)
- "EAI" - not defined
- "DB.SCHEMA.TABLE" - syntax not explained for new users
- "JSON" - not defined
Overall WCAG Writing Score: Needs Significant Work
This content significantly exceeds the Grade 12 target and needs revision. Here are 3 specific suggestions:
1. Break up extremely long sentences (average 35.6 words per sentence)
- Current: "A Data Group is a collection of data tables that are grouped together for easier organization and cross-table linkage."
- Suggested: "A Data Group is a collection of data tables. It groups tables together for easier organization. You can also link tables together within a Data Group."
2. Simplify the opening paragraph into shorter, clearer sentences
- Current: "Creating a Data Group for tables that went through General Onboarding is optional, while all Privacy Hub tables must be associated with a Data Group."
- Suggested: "You can create a Data Group for General Onboarding tables. This is optional. However, Privacy Hub tables must have a Data Group."
3. Break procedural sentences into smaller steps
- Current: "If your data tables have not yet been loaded to the Datavant Connect Platform as General Onboarding, you will need to load them before creating your Data Group."
- Suggested: "First, check if your tables are loaded. If not, load them before you create a Data Group. See the General Onboarding User Guide for help."
Plain Language: Needs Attention - Uses compound sentences with multiple clauses that could be simplified. Phrases like "cross-table linkage" and "join criteria to join tables" are unnecessarily complex.
Sentence Length: Fails - Multiple sentences exceed 25 words:
- "A Data Group is a collection of data tables that are grouped together for easier organization and cross-table linkage." (20 words - borderline)
- "Creating a Data Group for tables that went through General Onboarding is optional, while all Privacy Hub tables must be associated with a Data Group." (26 words)
- "If your data tables have not yet been loaded to the Datavant Connect Platform as General Onboarding, you will need to load them before creating your Data Group." (30 words)
- "Select the Site that is associated with your data tables, and select the tables that should be linked to this Data Group" (21 words - borderline)
- "Click Edit under the Data Group Details section to revise the Data Group Name, Description, Data Type, and/or upload a Data Dictionary" (23 words - borderline)
- "Click Create New Linkages under the Table Linkage section if you would like to create a join criteria to join tables within the Data Group together" (28 words)
- "Click Add Table either using the Add Table button found in the top right corner of the Data Group details page, or the + Add Tables link under the Tables section" (32 words)
Jargon: Needs Attention - Several unexplained technical terms:
- "Data Group" (explained, but definition is complex)
- "cross-table linkage" (unexplained)
- "Privacy Hub" (unexplained context)
- "Site" (unclear what this means in context)
- "join criteria" (unexplained technical term)
- "Data Dictionary" (unexplained)
Active Voice: Pass - Most instructions use active voice and imperative mood appropriately ("Click Create Data Group", "Select the Site", "Navigate to").
Heading Clarity: Pass - Step-by-step headings are clear and numbered logically (Step 1, Step 2, Step 3).
Link Text: Needs Attention - Contains vague link text:
- "refer to What is a Table, Segment, and Data Group?" - Link text is acceptable but could be clearer
- "refer to General Onboarding User Guide" - Missing article "the"
- Email "support@datavant.com" is clear
Abbreviations: Pass - No unexplained abbreviations found.
Overall WCAG Writing Score: Needs Significant Work
The content exceeds the Grade 12 target and needs simplification. Here are 3 specific suggestions:
1. Break up extremely long sentences - The second sentence is 44 words long: "In other words, any time tokenization occurs using a site owned by your company, any time transformation occurs using a site owned by your company, and any time transformation occurs for a site that is linked with a partner, a log entry will be posted."
Rewrite as: "A log entry is posted when: tokenization occurs using your company's site, transformation occurs using your company's site, or transformation occurs for a partner-linked site."
2. Simplify the opening sentence - "The software activity log page displays logs that indicate each time one of your company's encryption keys is accessed" (19 words with nested clauses).
Rewrite as: "The software activity log page shows when your company's encryption keys are accessed."
3. Break the filtering instruction into steps - The final sentence is 26 words with complex navigation.
Rewrite as: "To filter a column: 1. Hover over the column header. 2. Click the hamburger icon. 3. Select your filter."
FK RECOMMENDATIONS:
Plain Language: Needs Attention - Phrases like "displays logs that indicate" could be simplified to "shows when." The phrase "In other words" signals the writer is re-explaining, suggesting the first explanation was too complex.
Sentence Length: Fail - Multiple sentences exceed 25 words:
- Sentence 2: 44 words (the "In other words..." sentence)
- Sentence 5: 32 words (the "Each log entry contains..." sentence)
- Final sentence: 26 words
Jargon: Needs Attention - Several technical terms lack explanation or context:
- "tokenization" (used but not defined)
- "transformation" (used but not defined)
- "token transformation" (compound term, unexplained)
- "encryption keys" (assumed knowledge)
Active Voice: Needs Attention - Several passive constructions found:
- "logs are only captured" → "the system only captures logs"
- "can be found" → "you can find"
- "a log entry will be posted" → "the system posts a log entry"
Heading Clarity: Pass - The heading "Understanding the Software Activity Logs" is clear and descriptive.
Link Text: Pass - No link text present in the cleaned prose (Settings > Activity is navigation instruction, not a link).
Abbreviations: Needs Attention - ">" appears as HTML entity instead of rendered symbol. No other abbreviations found, but technical terms should be expanded on first use.
Overall WCAG Writing Score: Needs Significant Work
This content is above the Grade 12 target and should be simplified. Here are three specific suggestions:
1. Break down complex compound sentences: The sentence "Projects that include Match involve additional steps to prepare and deliver data" followed by dense list structures creates cognitive overload. Separate the explanation of Match projects from the procedural steps. Instead of embedding multiple concepts, use: "Some projects include Match. These projects need extra steps. You must prepare your data first. Then you deliver it."
2. Simplify the technical phrasing in key instructions: The phrase "Follow the instructions in the General Onboarding guide to ensure that the Datavant tokens in the file(s) you plan to deliver are in the correct transit encryption key" (27 words) is overly complex. Simplify to: "Check your Datavant tokens. Make sure they use the correct encryption key. See the General Onboarding guide for steps."
3. Reduce multi-clause constructions: The sentence "Any custom Datavant tokens in your data will need to be transformed to the correct transit encryption prior to delivery" contains unnecessary passive voice and complexity. Revise to: "Transform your custom Datavant tokens before delivery. Use the correct transit encryption."
Plain Language: Needs Attention - Multiple instances of unnecessarily complex phrasing such as "transit encryption key," "onboarding Configuration(s)," and "transform any files containing tokens to the privacy_solutions encryption" without clear definitions.
Sentence Length: Flag - Several sentences exceed 25 words:
- "Follow the instructions in the General Onboarding guide to ensure that the Datavant tokens in the file(s) you plan to deliver are in the correct transit encryption key." (29 words)
- "When working with Datavant's Privacy Solutions team for projects involving Expert Determinations, Remediations, or other privacy services, you will need to deliver the relevant data securely to Privacy Solutions." (30 words)
Jargon: Needs Attention - Unexplained technical terms include:
- Transit encryption key
- Tokens (used extensively without initial definition)
- Zip3
- PGP encryption
- AWS IAM
- SFTP
- S3 Transfer
- Onboarding Configuration(s)
Abbreviations: Needs Attention - Multiple unexplained abbreviations:
- PGP (Pretty Good Privacy)
- AWS (Amazon Web Services)
- IAM (Identity and Access Management)
- SFTP (Secure File Transfer Protocol)
- S3 (Simple Storage Service)
Active Voice: Needs Attention - Several passive constructions found:
- "will need to be delivered"
- "will need to be transformed"
- "were delivered successfully"
Consider: "You must deliver" / "You must transform" / "delivered successfully"
Heading Clarity: Pass - Headings like "Path 1: If Your Project Includes Match" and "Key Components" are clear and descriptive.
Link Text: Pass - No vague "click here" links detected; links reference specific guides and methods.
Overall WCAG Writing Score: Needs Significant Work
The article requires simplification of sentence structure, definition of technical terms at first use, expansion of abbreviations, and reduction of passive voice to meet accessibility standards and the Grade 12 readability target.
This content exceeds the Grade 12 target and needs simplification. Here are three specific suggestions:
1. Break down long, multi-clause sentences - Example: "As with previous versions, Datavant v4 and above require the ability to make an outbound network connection over port 443."
- Simplify to: "Datavant v4 needs an outbound network connection. Use port 443."
2. Simplify technical explanations - Example: "These connections enable the application to access cryptographic secrets (master salt, encryption keys), as well as configuration information."
- Simplify to: "These connections let the application access secrets (master salt and encryption keys) and configuration information."
3. Use shorter sentences in the overview - Example: "If you run DeID or Link in an automated pipeline, refer to Configure Datavant CLI in an Automated Pipeline for recommendations on staggering credential use to prevent unplanned downtime."
- Break into: "Do you run DeID or Link in an automated pipeline? See Configure Datavant CLI in an Automated Pipeline. It shows how to stagger credential use. This prevents unplanned downtime."
Plain Language: Needs Attention - Phrases like "cryptographic secrets," "staggering credential use," and "site-specific password is needed" could be simplified or explained more clearly for non-expert users.
Sentence Length: Needs Attention - Several sentences exceed 25 words:
- "As with previous versions, Datavant v4 and above require the ability to make an outbound network connection over port 443." (21 words - acceptable)
- "These connections enable the application to access cryptographic secrets (master salt, encryption keys), as well as configuration information." (18 words - acceptable)
- "If you run DeID or Link in an automated pipeline, refer to Configure Datavant CLI in an Automated Pipeline for recommendations on staggering credential use to prevent unplanned downtime." (30 words - too long)
Jargon: Needs Attention - Multiple unexplained technical terms:
- "master salt" (explained in parentheses but not defined)
- "encryption keys" (mentioned but not defined)
- "outbound network connection"
- "port 443" (no context for why this specific port)
- "authentication file" vs "authentication_file" (inconsistent)
Active Voice: Pass - Most sentences use active voice effectively ("Download," "Retrieve," "Modify")
Heading Clarity: Pass - Step-based headings are clear and action-oriented (Step 1. Configure your network, Step 2. Download the v4 application, etc.)
Link Text: Needs Attention - Some link references are vague:
- "For more information, see v4 Upgrade FAQs" (acceptable)
- "Refer to Use Datavant CLI in Batch Mode" (acceptable)
- "refer to Configure Datavant CLI in an Automated Pipeline" (acceptable but could be more specific about what readers will learn)
Abbreviations: Needs Attention - Several unexplained abbreviations:
- "CLI" (explained on second use but not on first mention in title)
- "DeID" (not spelled out; appears to mean "de-identification")
- "v3" and "v4" (clear from context but not explicitly defined as "version")
- "FAQs" (common abbreviation but not spelled out)
Overall WCAG Writing Score: Needs Attention
This content exceeds the Grade 12 target and needs revision. Here are three specific suggestions:
1. Break down long, complex sentences - The article contains multiple sentences over 25 words. For example: "The Ecosystem Explorer found on the Partners page showcases Datavant partners who have opted to make themselves visible on the Datavant platform" (23 words) and "Business or Sales Teams who are evaluating potential Datavant partnerships by assessing data availability, running overlaps via Assess, or making introductions" (22 words). Break these into shorter, single-idea sentences.
2. Simplify compound explanations - The sentence "Organizations must be visible in Explore to run Assess reports with On Demand data" combines multiple concepts. Split this into: "Organizations must be visible in Explore. This allows them to run Assess reports with On Demand data."
3. Use simpler vocabulary and structure - Replace phrases like "particularly helpful for two types of users" with "helps two types of users" and "showcases Datavant partners who have opted to make themselves visible" with "shows Datavant partners who chose to be visible."
Plain Language: Needs Attention - Contains corporate jargon and nested clauses. Examples: "opted to make themselves visible," "showcases Datavant partners," "navigate to the Download button"
Sentence Length: Needs Attention - Multiple sentences exceed 25 words:
- "The Ecosystem Explorer page is particularly helpful for two types of users: Business or Sales Teams who are evaluating potential Datavant partnerships by assessing data availability, running overlaps via Assess, or making introductions." (33 words)
- "If you would like to make your company profile visible in order to get the most out of business opportunities, you can enable your visibility on the Company Profile page." (31 words)
- "Table Accessibility indicates how you allow partners to view and interact with your data tables." (15 words - acceptable, but could be clearer)
Jargon: Needs Attention - Several terms lack explanation:
- "Assess reports"
- "On Demand data"
- "Profile Model data"
- "table metadata"
- "ICD" (unexplained abbreviation)
Active Voice: Needs Attention - Multiple passive constructions found:
- "will be visible by default"
- "are required" (in "not all fields are required")
- "will be visible depending on"
- "is made available" (in "Only the table metadata such as name and description is made available")
Heading Clarity: Needs Attention - The article appears to lack clear hierarchical headings. "Viewing a Company Profile" is the only visible heading, but context suggests more structure is needed (e.g., "Navigating the Ecosystem Explorer," "Using Filters," "Exporting Data").
Link Text: Cannot assess - No hyperlink text is visible in the cleaned prose, though references like "Refer to Manage your Company Profile in Explore" suggest links exist. Ensure link text is descriptive, not just "click here."
Abbreviations: Needs Attention:
- "PDF" - commonly understood, likely acceptable
- "CSV" - commonly understood in technical contexts, likely acceptable
- "ICD" - NOT explained and domain-specific medical coding term that requires definition
Overall WCAG Writing Score: Needs Significant Work
1. Break down long sentences (average 27.3 words per sentence)
- Example: "The TABLE_EXISTS column does not only indicate if a table exists or has been deleted, it could also indicate that a user has no permission to access the table, which will show up as FALSE."
- Suggestion: Split into two sentences: "The TABLE_EXISTS column indicates if a table exists or has been deleted. It can also indicate that a user has no permission to access the table. This will show as FALSE."
2. Simplify complex multi-clause sentences
- Example: "The following requirements will need to be met in order to run the procedure successfully:"
- Suggestion: "Meet these requirements to run the procedure successfully:"
3. Use bulleted lists to break up dense procedural content
- The long paragraph listing role requirements should be reformatted as a numbered or bulleted list with one requirement per line. This reduces cognitive load and improves scannability.
Plain Language: Needs Attention - Phrases like "Deviating from this could cause unforeseen issues" and "in order to run the procedure successfully" could be simplified. Use "To run the procedure successfully" and "This may cause unexpected problems."
Sentence Length: Needs Attention - Multiple sentences exceed 25 words:
- "The TABLE_EXISTS column does not only indicate if a table exists or has been deleted, it could also indicate that a user has no permission to access the table, which will show up as FALSE." (34 words)
- "The following requirements will need to be met in order to run the procedure successfully:" (14 words - acceptable, but could be shorter)
Jargon: Needs Attention - Technical terms used without explanation:
- "native app application"
- "LAST_QUERY_ID()"
- "RESULT_SCAN"
- "cursor"
- "information_schema"
- "current context"
Consider adding a brief glossary or inline definitions for users unfamiliar with Snowflake-specific terminology.
Active Voice: Needs Attention - Several passive constructions found:
- "has been deleted"
- "will need to be met"
- "should be run"
- "The role used should have access"
Suggestion: "Delete the table" / "Meet these requirements" / "Run the call statement" / "The role needs access"
Heading Clarity: Needs Attention - Only one heading found ("Step 2: Create Function"). Article needs hierarchical structure with clear headings like "Overview," "Prerequisites," "Permissions Required," and "Understanding the Output."
Link Text: Pass - No links detected in the cleaned prose text.
Abbreviations: Pass - SQL and FALSE/TRUE are industry-standard and contextually clear.
Overall WCAG Writing Score: Needs Significant Work
Since this article scores above Grade 12, here are three specific suggestions to improve readability:
1. Break down complex compound sentences with multiple clauses:
- Current: "By enabling multi-instance installs of the Datavant Snowflake Native application, you can run one application multiple times in a single Snowflake account."
- Suggested: "Enable multi-instance installs of the Datavant Snowflake Native application. This lets you run one application multiple times in a single Snowflake account."
2. Simplify multi-syllable technical phrases where possible:
- Current: "Operational flexibility. You can enable independent initialization, references (secrets / external integrations), and telemetry per instance."
- Suggested: "Operational flexibility. You can set up each instance with its own initialization, secrets, external integrations, and telemetry."
3. Split the long instructional sentence in the installation section:
- Current: "If you already have an instance of the Snowflake installed, you can create additional named instances directly."
- Suggested: "Do you already have an instance of Snowflake installed? You can create additional named instances directly."
FK
Plain Language: Needs Attention
- Phrases like "independent initialization, references (secrets / external integrations), and telemetry per instance" contain nested technical concepts that should be unpacked
- "Schema/database placement" assumes knowledge without explanation
Sentence Length: Pass
- All sentences are under 25 words, which is good for accessibility
Jargon: Needs Attention
- "listing_id" - not explained
- "telemetry" - not explained
- "external access integrations" - not explained
- "network rules" - not explained in context
- "schema/database placement" - not explained for non-experts
Active Voice: Good
- Most instructions use active voice ("Run Show Applications", "Create a secret", "Use this query")
- One passive construction: "Both your original and newly created instances should display" (acceptable for this context)
Heading Clarity: Pass
- Headings are clear and descriptive ("Important Implementation Considerations", "How to Enable Multiple Instances")
Link Text: Not Applicable
- No links present in the cleaned text
Abbreviations: Needs Attention
- "ENV" - used in example code but not explained as "environment"
- "DEV" - not explicitly defined as "developer"
- "TEST" - clear enough in context but could benefit from initial definition
Overall WCAG Writing Score: Needs Attention
The article has good structure and sentence length, but needs work on explaining technical terms and simplifying complex phrases to meet WCAG 2.2 Level AAA plain language guidelines.
This content exceeds the Grade 12 target and needs simplification. Here are three specific suggestions:
1. Break down long sentences: The average sentence length is 29.7 words, which significantly inflates the FK score. For example, "This article will review the different data table permission types that will impact how partners can access tables to use in Assess" (21 words) could become two sentences: "This article reviews data table permission types. These permissions impact how partners access tables in Assess."
2. Simplify the list introductions: The sentence "When creating a new Assess report, there are three categories of tables you will be able to choose from:" (18 words) could be shortened to "When creating a new Assess report, choose from three table categories:" (12 words).
3. Reduce complex multi-clause constructions: "If you do not own your data tables and want to run an Assess report on partner tables, tables that are shared with you or available as On Demand must have the Third-party Overlap permission enabled" (36 words) should be broken into 2-3 shorter sentences focusing on one idea each.
Plain Language: Needs Attention - The text uses platform-specific terminology without sufficient context (e.g., "Third-party Overlap permission," "export-tokens, overlap, profile"). While some technical terms are necessary, plain language explanations would improve accessibility.
Sentence Length: Needs Attention - Multiple sentences exceed 25 words:
- "If you do not own your data tables and want to run an Assess report on partner tables, tables that are shared with you or available as On Demand must have the Third-party Overlap permission enabled." (36 words)
- "This article will review the different data table permission types that will impact how partners can access tables to use in Assess." (21 words)
- "Subscribing to notifications whenever an activity is performed Applying filters to the activity page by User, Company, Tables, and Action (export-tokens, overlap, profile) Exporting the activity list as a CSV" (This appears to be a malformed list)
Jargon: Needs Attention - Several unexplained technical terms:
- "Third-party Overlap permission" (not defined)
- "export-tokens" (not explained)
- "On Demand Tables" (mentioned but not fully explained)
- "By Request" (referenced but explanation deferred to another guide)
Active Voice: Pass - Most sentences use active voice appropriately. One passive construction found: "will be logged by both partners" could be "both partners will log this."
Heading Clarity: Needs Attention - The article lacks structural headings to break up the content. Recommend adding headings like "Table Permission Types," "Monitoring Data Activity," and "Third-party Overlap Requirements."
Link Text: Pass - Link references are descriptive (e.g., "Share a Table in Portal," "Ecosystem Explorer User Guide").
Abbreviations: Pass - "CSV" is commonly understood in the target audience context.
Overall WCAG Writing Score: Needs Attention
This content exceeds the Grade 12 target and needs simplification. Here are three specific suggestions:
1. Break down long, complex sentences - The article averages 26.8 words per sentence, well above the ideal 15-20 words. Example to revise:
- Current: "The goal of Assess is to provide tools to reduce friction in data exchange, specifically at the exploratory or pre-sales feasibility step by enabling you to quickly evaluate data tables and cohorts of interest."
- Suggested: "Assess reduces friction in data exchange. It helps you quickly evaluate data tables and cohorts during exploratory or pre-sales phases."
2. Simplify nested clauses and prepositional phrases - Example to revise:
- Current: "Customers who find value in our Assess tools may also benefit from Datavant's Segment Builder, which is a cohorting tool to help subset or join tables."
- Suggested: "Do you find Assess useful? Try Datavant's Segment Builder next. It helps you subset or join tables."
3. Front-load key information and use shorter bullet points - Example to revise:
- Current: "Evaluating potential partnerships more easily by running overlaps and getting granular with targeting (e.g. demographics, service year, medical codes, etc..)"
- Suggested: "Evaluate partnerships more easily. Run overlaps and target specific data like demographics, service year, or medical codes."
Plain Language: Needs Attention
- "cohort discovery and evaluation" - technical jargon in opening sentence
- "tokenized and de-identified data table" - compound technical phrase needs explanation
- "compute unique individuals on Tokens 1 and 2" - unclear what this means to new users
- "fill rates" - unexplained technical term
Sentence Length: Needs Attention
Multiple sentences exceed 25 words:
- "The goal of Assess is to provide tools to reduce friction in data exchange, specifically at the exploratory or pre-sales feasibility step by enabling you to quickly evaluate data tables and cohorts of interest." (35 words)
- "A tokenized and de-identified data table must be onboarded to the Datavant Connect Platform to utilize the Assess tools along with other important considerations and requirements:" (28 words)
- "Users can filter the overlap on various Profile Model fields and can view the fill rates if one or more partners overlapping within Assess include common Profile Model fields within the data tables." (35 words)
- "If you are onboarding profile model fields, ensure the data fields are mapped to the corresponding Profile Model Mapping fields in the onboarding configuration." (26 words)
Jargon: Needs Attention
Unexplained technical terms:
- "feasibility tool"
- "cohort discovery"
- "tokenized and de-identified"
- "metadata"
- "Tokens 1 and 2"
- "error tokens"
- "Profile Model fields"
- "fill rates"
- "onboarding configuration"
- "subscription tier"
Active Voice: Needs Attention
Passive constructions found:
- "must be onboarded" → Consider: "you must onboard"
- "are not included" → Consider: "Assess does not include"
- "can be changed" → Consider: "you can change this"
- "can be included" → Consider: "you can include"
- "are mapped" → Consider: "map the data fields"
- "are only available" → Consider: "only select customers can access"
Heading Clarity: Pass
Headings are clear and hierarchical (Overview, About Assess, How it Works, Assess Report Types)
Link Text: Needs Attention
- "Learn more about Error Tokens here: Error Tokens" - includes "here" which is discouraged
- "Learn more about Working with a Partner with Assess" - this passes as descriptive
- Consider: "Read about error tokens" or "View error token documentation"
Abbreviations: Needs Attention
- "e.g." - used without expansion (should be "for example")
- "ICD codes" - not expanded on first use (International Classification of Diseases)
Overall WCAG Writing Score: Needs Significant Work
This content exceeds the recommended Grade 12 target and needs simplification. Here are 3 specific suggestions:
1. Break down complex noun phrases: Change "maintains a list of configurations across all sites that are part of your company" to "shows all configurations for your company's sites." This reduces word count and syllable density.
2. Simplify technical explanations: The sentence "This ratio shows us there are 6 data elements + 30 tokens" could be rewritten as "This means: 6 data elements plus 30 tokens." Use shorter, more direct phrasing throughout.
3. Split longer sentences: The sentence "In contrast to a configuration clone, this creates a 'link' between the configurations where updates you make are automatically propagated to the si[te]" (appears truncated) should become two sentences: "This is different from cloning. It creates a link between configurations. Updates you make are sent automatically to the site."
Plain Language: Needs Attention - Contains complex phrases like "automatically propagated," "historical copy is saved," and "maintains a list of configurations across all sites that are part of your company."
Sentence Length: Pass - Most sentences stay under 25 words, though some approach this limit.
Jargon: Needs Attention - Several unexplained technical terms:
- "ellipsis" (UI term not explained for non-technical users)
- "legacy configurations"
- "schema"
- "transit key"
- "connect key"
Active Voice: Needs Attention - Multiple passive constructions found:
- "can be accessed"
- "are part of"
- "is created"
- "are sorted alphabetically"
- "is being onboarded"
- "are saved"
Heading Clarity: Needs Attention - "Overview" and "Configuration Page" are clear, but "Important Considerations" could be more specific (e.g., "Configuration Name Limitations"). The heading structure appears incomplete (text seems truncated).
Link Text: Cannot assess - No link text present in cleaned prose text.
Abbreviations: Pass - "UTC" is a standard abbreviation in technical contexts, though defining it on first use would help (Coordinated Universal Time).
Overall WCAG Writing Score: Needs Attention
Since this content exceeds Grade 12, here are three specific suggestions to improve readability:
1. Break down long, complex sentences with multiple clauses
- Current: "Distribution enables a simple and efficient process for Datavant partners to deliver and receive data tables using one single integration instead of having to manage multiple integrations with multiple recipients."
- Suggested: "Distribution enables a simple process. Datavant partners can deliver and receive data tables using one integration. This means you don't need to manage multiple integrations with multiple recipients."
2. Simplify technical explanations and remove nested information
- Current: "While Datavant performs some basic format checks on the fields that are processed during data onboarding, some fields (e.g. clinical values) may be configured to pass through without modification."
- Suggested: "Datavant performs basic format checks during data onboarding. However, some fields may pass through without modification. For example, clinical values may not be checked."
3. Convert long procedural sentences into bulleted lists or shorter statements
- Current: "Therefore, it is possible that incorrectly placing PHI values in these pass-through fields could result in leakage into the output file."
- Suggested: "Warning: Incorrectly placing PHI values in pass-through fields can cause data leakage. Always verify your field placement."
Plain Language: Needs Attention - Contains complex noun phrases like "remediated Privacy Hub tables," "Token Export results from an Overlap report," and "certified data loaded" without clear definitions or context for new users.
Sentence Length: Needs Attention - Multiple sentences exceed 25 words:
- "Distribution enables a simple and efficient process for Datavant partners to deliver and receive data tables using one single integration instead of having to manage multiple integrations with multiple recipients." (31 words)
- "While Datavant performs some basic format checks on the fields that are processed during data onboarding, some fields (e.g. clinical values) may be configured to pass through without modification." (31 words)
- "Therefore, it is possible that incorrectly placing PHI values in these pass-through fields could result in leakage into the output file." (23 words - acceptable but close to limit)
Jargon: Needs Attention - Multiple unexplained technical terms:
- "certified" (in context of data tables)
- "remediated"
- "Token Export"
- "Overlap report"
- "PHI values" (mentioned but not defined)
- "pass-through fields"
- "data onboarding"
- "ingestion"
Abbreviations: Needs Attention
- "PHI" - used but not defined (Protected Health Information)
- "e.g." - should spell out as "for example" for accessibility
Active Voice: Needs Attention - Several passive constructions found:
- "Distributions can only be enabled by Datavant"
- "some fields...may be configured to pass through"
- "data is already onboarded to the Datavant Connect Platform"
- "Files are distributed shortly after ingestion"
Heading Clarity: Pass - The main heading "Understanding Distributions" is clear, and the subheading "How to Manage Distributions" accurately describes its content.
Link Text: Pass - Link references like "Pick up Distributed Data," "Request an External File Push," and "Send Distributed Data to a Partner" are descriptive and indicate destination clearly.
Overall WCAG Writing Score: Needs Attention
The article would benefit from defining technical terms on first use, breaking long sentences into shorter ones, converting passive voice to active voice where possible, and spelling out abbreviations to improve accessibility for all users.
This content exceeds the Grade 12 target and needs simplification. Here are 3 specific suggestions:
1. Break down long, complex sentences: The sentence "However, for the Expert Determination analysis we do not necessarily need to see all the patient records within a dataset to certify it as de-identified (subject to the conditions within the report); instead, we can be provided with a representative sample of the whole dataset which would allow us to draw our conclusions while not having to review a vastly larger amount of data" is 68 words long. Split this into 2-3 shorter sentences, such as: "However, the Expert Determination analysis does not require all patient records. We can certify a dataset as de-identified using a representative sample. This allows us to draw conclusions without reviewing vastly larger amounts of data."
2. Simplify dense technical explanations: The sentence "Sampling criteria requires that the sample is random and not subject to any bias, ensuring that it depicts an accurate representation of the wider dataset" can be rewritten as: "The sample must be random and unbiased. This ensures it accurately represents the full dataset."
3. Use bullet points for complex numerical examples: The paragraph explaining "1 million patients or 10% of the patients within the whole dataset, whichever is largest" with two examples would be clearer as a bulleted list with clear if/then statements.
Plain Language: Needs Attention - Contains unnecessarily complex phrasing such as "we do not necessarily need to see all the patient records within a dataset to certify it as de-identified (subject to the conditions within the report)" which could be simplified.
Sentence Length: Needs Significant Work - Multiple sentences exceed 25 words:
- 68 words: "However, for the Expert Determination analysis we do not necessarily need..."
- 39 words: "The Privacy Solutions recommendation is that the random sampling must cover..."
- 50 words: "For example, if the dataset contains 3 tables, the same 1 million or 10%..."
- 33 words: "Sample 1 million or 10% of the patients (whichever is largest) from the table..."
Jargon: Needs Attention - Several terms lack explanation:
- "Expert Determination analysis" (used without definition)
- "de-identified" (not explained for general audience)
- "Master Patient table" (technical database concept)
- "pseudo code" (programming term)
Active Voice: Needs Attention - Several passive constructions found:
- "the sample is random and not subject to any bias"
- "is performed" (appears twice)
- "should be selected"
- "the sampling is performed"
Heading Clarity: Pass - Headings (Overview, Criteria, Common Questions) are clear and descriptive.
Link Text: Cannot assess - No link text present in the cleaned prose provided.
Abbreviations: Needs Attention - "Mil" is used without first spelling out "million" in the pseudo code section.
Overall WCAG Writing Score: Needs Significant Work
This content exceeds the Grade 12 target and needs simplification. Here are 3 specific suggestions:
1. Break down complex sentences with multiple clauses
- Current: "A comprehensive data dictionary will allow this step, and the overall ED process, to be quicker and simpler for all parties."
- Suggested: "A comprehensive data dictionary speeds up this step. It also makes the overall ED process quicker and simpler."
2. Simplify dense technical phrases
- Current: "Significant sources of risk can be present in variables which appear to carry only negligible risk at a high level view (particularly relevant where no data is assessed)."
- Suggested: "Some variables may look low-risk at first. But they can still pose significant disclosure risks. This is especially true when we cannot review the actual data."
3. Reduce prepositional phrase stacking
- Current: "The starting point for Privacy Solutions's expert determination (ED) process is a robust, accurate data dictionary (DD): a collection of names, definitions, and attributes about data elements that are being assessed in our project."
- Suggested: "We start every expert determination (ED) with a data dictionary (DD). This document lists the names, definitions, and attributes of all data elements we assess."
Plain Language: Needs Attention - Multiple instances of complex phrasing:
- "facilitate a full and thorough Expert Determination" (use "support" instead of "facilitate")
- "minimize back and forth" (informal idiom - use "reduce communication delays")
- "particularly relevant where no data is assessed" (unclear what this parenthetical means)
Sentence Length: Needs Attention - Several sentences exceed 25 words:
- "In order to facilitate a full and thorough Expert Determination, Privacy Solutions requires a robust and accurate data dictionary to describe the provided data." (25 words - borderline)
- "Moreover, the cleaner and more error-free the data is, the smoother and quicker the privacy analysis will be." (17 words - Pass)
- "The Privacy Solutions process contains a data quality check stage prior to the commencement of the Expert Determination in order to speed up timelines and gather as much necessary information as possible to minimize back and forth." (37 words - Too long)
- "A comprehensive data dictionary will allow this step, and the overall ED process, to be quicker and simpler for all parties." (20 words - Pass)
- "The starting point for Privacy Solutions's expert determination (ED) process is a robust, accurate data dictionary (DD): a collection of names, definitions, and attributes about data elements that are being assessed in our project." (38 words - Too long)
Jargon: Needs Attention - Several technical terms introduced without adequate explanation:
- "Expert Determination" (abbreviated to ED but not clearly defined until later)
- "disclosure risk" (not explained)
- "header misalignment" (technical term not defined)
- "delimiter" (technical term not defined for non-technical users)
- "standardized code sets" (not explained)
Abbreviations: Needs Attention
- ED (Expert Determination) - defined on second use, should be defined on first use in Overview
- DD (Data Dictionary) - defined properly
- Note: The article cuts off but appears to reference format configurations without full context
Active Voice: Needs Attention - Multiple passive constructions:
- "are being assessed in our project" → "we assess in our project"
- "Analysis will be completed" → "We will complete analysis"
- "Specific recommendations can be made" → "We can make specific recommendations"
- "the data is assessed" → "we assess the data"
Heading Clarity: Pass - Headings are clear and descriptive ("What is a Data Dictionary?", "Data Dictionary Requirements", "Common Issues with Data Dictionaries")
Link Text: Cannot assess - No links present in the cleaned prose text provided
Overall WCAG Writing Score: Needs Attention
The article has good structure and headings but requires work on sentence complexity, passive voice reduction, jargon explanation, and plain language to meet WCAG 2.2 AAA writing guidelines and serve a broader audience effectively.
This content exceeds the Grade 12 target. Here are 3 specific suggestions:
1. Break down complex compound sentences: The sentence "Confident standardization is stricter, matching only name variations that are closely similar, which leads to higher precision" (19 words) combines multiple concepts. Split into: "Confident standardization is stricter. It matches only name variations that are closely similar. This leads to higher precision."
2. Simplify technical explanations: The phrase "Probabilistic matching is matching that uses values that may not be unique, however when used in combination, they provide a high probability that the correct individual is matched" is dense. Rewrite as: "Probabilistic matching uses multiple data points together. Each point alone may not be unique. But combining them helps identify the correct person."
3. Reduce multi-clause sentences: The sentence "Errors can occur due to data entry mistakes (such as a mistyped SSN) or limitations in the dataset (for example, SSNs may be missing from many records)" contains nested examples. Simplify to: "Errors can happen. Data entry mistakes like mistyped SSNs cause problems. Missing data also reduces accuracy."
Plain Language: Needs Attention - Heavy use of technical terminology without sufficient context for non-experts. Terms like "cascading or hierarchical token matching," "false positive and false negative rates," and "zip3" assume specialized knowledge.
Sentence Length: Needs Attention - Multiple sentences exceed 25 words:
- "Different tokens produce different false positive and false negative rates when used to match records across tables." (17 words - acceptable)
- "Probabilistic matching is matching that uses values that may not be unique, however when used in combination, they provide a high probability that the correct individual is matched." (29 words - too long)
- "Confident standardization is stricter, matching only name variations that are closely similar, which leads to higher precision." (17 words - acceptable)
- Several token description bullets contain parenthetical information that increases cognitive load
Jargon: Needs Attention - Unexplained or insufficiently explained terms:
- "PII" (defined in parentheses, good practice)
- "cascading or hierarchical token matching" (not defined)
- "false positive and false negative rates" (not defined)
- "zip3" (not defined - unclear what this means)
- "Soundex" (not defined)
- "Metaphone" (not defined)
- "metaphone standardization" (partial explanation at end, but comes after first use)
- "Administrative Gender" (not defined)
- "precision" vs "recall" (used without definition)
Active Voice: Pass with minor concerns - Mostly active voice used effectively. One passive construction: "Errors can occur due to data entry mistakes" could be "Data entry mistakes cause errors."
Heading Clarity: Pass - Headings are clear and descriptive ("Use deterministic tokens first," "Use probabilistic tokens from common fields")
Link Text: Cannot assess - No link text present in the cleaned prose provided
Abbreviations: Needs Attention:
- "PII" - expanded on first use ✓
- "SSN" - expanded on first use ✓
- "DOB" - never expanded (used extensively throughout)
- "zip3" - never explained
Overall WCAG Writing Score: Needs Attention
The article makes good structural choices with clear headings and some definitions, but requires work on sentence complexity, comprehensive jargon definitions (especially DOB and zip3), and reducing technical density for broader accessibility.
This content is above the Grade 12 target and needs simplification. Here are 3 specific suggestions:
1. Break down complex compound sentences: The sentence "Explicit patient information, such as sex or date of birth, directly reveals information about a patient (e.g., that the patient is male or the patient's age)" can be split into: "Explicit patient information includes sex or date of birth. This information directly reveals facts about a patient. For example, it shows that the patient is male or shows the patient's age."
2. Simplify technical explanations: The sentence "Thus, the ability to uniquely (or near uniquely) re-identify an individual within a given dataset depends on explicit or implicit patient information contained therein" should become: "An individual can be re-identified in a dataset based on two types of information: explicit and implicit patient information."
3. Reduce nested clause structures: Replace "To ensure that the re-identification risk associated with the data is sufficiently low to be certified as de identified under the HIPAA privacy law, our team will analyze the re-identification risk of each individual based on the information in the data" with shorter sentences: "Our team analyzes re-identification risk for each individual. We use the information in the data to do this. This ensures the risk is low enough to meet HIPAA privacy law requirements for de-identified data."
Plain Language: Needs Attention - Contains overly formal phrases like "contained therein," "reasonably available information," and "remediations package." Replace with simpler alternatives: "in the data," "publicly available information," and "customized solution."
Sentence Length: Needs Attention - Multiple sentences exceed 25 words:
- "Generally, the more information present for a given individual, the greater the risk of re-identification is for that individual." (18 words - Pass)
- "Thus, the ability to uniquely (or near uniquely) re-identify an individual within a given dataset depends on explicit or implicit patient information contained therein." (26 words - FLAG)
- "To ensure that the re-identification risk associated with the data is sufficiently low to be certified as de identified under the HIPAA privacy law, our team will analyze the re-identification risk of each individual based on the information in the data (both explicit and implicit), combined with reasonably available information (e.g., information in the public domain)." (60 words - MAJOR FLAG)
Jargon: Needs Attention - Several technical terms lack explanation:
- "cohort" (used without definition)
- "remediations" (technical term, consider "changes" or "adjustments")
- "granularity" (used multiple times without explanation)
- "de identified" (HIPAA term needing brief explanation)
- "binned" (statistical jargon)
Abbreviations: Pass - HIPAA is explained on first use as "HIPAA privacy law"
Active Voice: Needs Attention - Several passive constructions found:
- "the procedure was performed" → "a provider performed the procedure"
- "can be used to infer" → "can reveal"
- "must be applied to the data" → "we must apply to the data"
- "is required" → "you need"
Heading Clarity: Needs Attention - The article has only one heading visible in the text. The questions section ("Here are some questions to consider:") should use a proper subheading like "Questions to Consider Before Project Kickoff."
Link Text: Cannot Assess - No link text is visible in the cleaned prose text provided.
Overall WCAG Writing Score: Needs Significant Work
1. Break down complex compound sentences
- Current: "Privacy Solutions statistical experts have produced 400+ Expert Reports for organizations across the healthcare data ecosystem and beyond and have analyzed a large variation of data types within the space."
- Recommended: "Privacy Solutions statistical experts have produced 400+ Expert Reports. We have analyzed many data types across the healthcare ecosystem."
2. Simplify terminology and reduce word density
- Current: "We also can integrate risk assessment automation into de-identification processes for certain data types and environments."
- Recommended: "We can also automate risk assessment for certain data types and environments."
3. Use shorter, more direct sentences in the opening paragraph
- Current: "Privacy Solutions by Datavant supports organizations across the healthcare ecosystem to ensure privacy protection of individuals through expert evaluation of data de-identification and use of our proprietary software solutions."
- Recommended: "Privacy Solutions by Datavant helps healthcare organizations protect individual privacy. We do this through expert evaluation of de-identified data and our proprietary software."
Plain Language: Needs Attention - Multiple instances of unnecessarily complex phrasing such as "positioned as if we are your disclosure risk function" and "potential to be sufficiently low so that they can proceed."
Sentence Length: Needs Attention - Several sentences exceed 25 words:
- "Privacy Solutions by Datavant supports organizations across the healthcare ecosystem to ensure privacy protection of individuals through expert evaluation of data de-identification and use of our proprietary software solutions." (29 words)
- "Privacy Solutions statistical experts have produced 400+ Expert Reports for organizations across the healthcare data ecosystem and beyond and have analyzed a large variation of data types within the space." (31 words)
- "We can support in development of new products, planning for dataset joins, or for analytics planning to ensure risk mitigation throughout; this helps builds go smoothly and supports discussions with your vendors and customers around privacy risk." (38 words)
Jargon: Needs Attention - The following terms are used without explanation:
- De-identification / de-identified (central term, needs early definition)
- Expert Determination (used repeatedly before explanation)
- Disclosure risk
- Dataset joins
- HIPAA standard (acronym used before explanation)
Active Voice: Needs Attention - Passive constructions found:
- "data that has been de-identified"
- "fields are added"
- "new sources are utilized"
- "The Privacy Solutions team is positioned as if we are..."
Heading Clarity: Pass - Headings are clear and ask direct questions that match user intent.
Link Text: Cannot assess - No link text present in the cleaned prose provided.
Abbreviations: Needs Attention
- "HIPAA" - used multiple times without first defining as "Health Insurance Portability and Accountability Act (HIPAA)"
Overall WCAG Writing Score: Needs Attention
1. Break down long, multi-clause sentences
- Current: "Publishing a company profile in Explore expands your company's visibility across the ecosystem and can lead to an increased number of potential partnership opportunities for your organization, whether for commercial, strategic, research, or non-profit collaborative purposes." (32 words)
- Suggested: "Publishing a company profile in Explore expands your company's visibility. This can lead to more partnership opportunities. These may be commercial, strategic, research, or non-profit collaborations."
2. Simplify vocabulary and reduce syllable-heavy words
- Replace "dynamically browse" with "search"
- Replace "potential partnership opportunities" with "partner opportunities"
- Replace "applicable" with "right for you"
- Replace "represented" with "included"
3. Shorten complex procedural sentences
- Current: "Follow the steps in this guide to set up your company's profile so that partners can easily find you in the Ecosystem Explorer tool." (24 words)
- Suggested: "Follow these steps to set up your profile. Partners can then find you in the Ecosystem Explorer."
Plain Language: Needs Attention
- Overly complex phrases: "dynamically browse for potential partners," "robust, detailed description"
- Business jargon used without context: "Distribution Ready," "onboarded to the Datavant Connect Platform"
Sentence Length: Needs Attention
- 32-word sentence: "Publishing a company profile in Explore expands your company's visibility across the ecosystem and can lead to an increased number of potential partnership opportunities for your organization, whether for commercial, strategic, research, or non-profit collaborative purposes."
- 29-word sentence: "Note that you will need to add Contacts for Introductions to make your company profile visible (refer to Step 2. Add Contacts for Introductions and Data Sharing)."
- 27-word sentence: "This lets partners know a company has tables that are onboarded to the Datavant Connect Platform and are ready to be delivered to an end recipient through the Datavant Distribution tool."
Jargon: Needs Attention
- "Ecosystem Explorer" (explained, but complex)
- "Distribution Ready" (partially explained)
- "onboarded" (unexplained technical term)
- "tables" (database tables - not explained in context)
- "end recipient" (could be simplified to "recipient")
- "Assess reports" (unexplained feature)
- "On Demand data" (unexplained)
Active Voice: Pass
Most sentences use active voice appropriately, though some passive constructions exist ("are onboarded," "are ready to be delivered").
Heading Clarity: Pass
Headings are clear and action-oriented ("Complete Company Profile," "Add Contacts for Introductions").
Link Text: Pass
Link references are descriptive ("Managing Users For Your Company," "Explore Profile Definitions").
Abbreviations: Pass
No unexplained abbreviations found.
Overall WCAG Writing Score: Needs Attention
The article would benefit from shorter sentences, simpler vocabulary, and better explanation of technical terms to improve accessibility for a broader audience.
1. Break up compound technical phrases: The text contains complex multi-word technical phrases like "convert site-specific tokens into transit tokens, preparing them for secure transfer to a partner" and "automatically create configurations from a data dictionary and associate tables with a single data group." Break these into shorter, simpler sentences. For example: "It shows how to convert site-specific tokens into transit tokens. This prepares them for secure transfer to a partner."
2. Simplify vocabulary choices: Replace polysyllabic words with simpler alternatives where possible. For instance, change "demonstrates" to "shows" throughout (though "shows" is already used in some places, "demonstrates" appears in video titles), "de-identification" could be explained as "removing identifying information," and "onboard" could be replaced with "upload" or "load" depending on context.
3. Reduce word density in descriptions: Several sentences pack multiple technical concepts together, such as "This video demonstrates how to use Datavant Desktop to tokenize identified data and prepare the resulting tokens for secure sharing with partners." Split this into: "This video shows how to use Datavant Desktop. You will tokenize identified data. Then you will prepare tokens for secure sharing with partners."
Plain Language: Needs Attention - Technical terms like "tokenize," "de-identification actions," "transit tokens," "site-specific tokens," and "data dictionary" are used without explanation or context for users unfamiliar with the platform.
Sentence Length: Pass - While some sentences approach the limit, none exceed 25 words. The longest sentences remain within acceptable bounds at approximately 22-24 words.
Jargon: Needs Attention - Unexplained technical terms include: "tokenize," "de-identification," "tokens," "transit tokens," "site-specific tokens," "configurations," "data dictionary," "data group," "ingestion errors," "Privacy Solutions," and "Expert Determinations." These should either be defined inline or linked to a glossary.
Active Voice: Pass - The article predominantly uses active voice construction ("This video demonstrates," "It shows"). No significant passive voice issues detected.
Heading Clarity: Needs Attention - Headings like "Datavant CLI: Transform Partner Tokens" and "Streamlined Onboarding in Privacy Solutions" assume familiarity with product terminology. Consider adding brief explanatory subtitles (e.g., "Transform Partner Tokens (Convert Received Tokens)").
Link Text: Pass - Link text appears descriptive and contextual ("Upgrade to Datavant v4," "Transform Tokens User Guide," "How to Use Datavant Desktop").
Abbreviations: Needs Attention - "CLI" appears multiple times without being spelled out as "Command Line Interface" on first use. "V4" should be written as "version 4" on first mention.
Overall WCAG Writing Score: Needs Attention
Since the score exceeds Grade 12, here are three specific suggestions:
1. Break down compound sentences with multiple clauses: The sentence "Smaller warehouse sizes may be adequate and more cost-effective for lower-scale workloads (100K rows), but as the scale increases, larger warehouses still provide better performance and scalability, especially for tokenization" contains 30 words and multiple ideas. Split it into: "Smaller warehouse sizes work well for lower-scale workloads (100K rows). They are also more cost-effective. However, larger warehouses provide better performance as scale increases, especially for tokenization."
2. Simplify technical compound phrases: Replace "the discrepancy between warehouse sizes becomes more apparent" with "differences between warehouse sizes become clearer" and "display the most noticeable improvements" with "show the biggest improvements."
3. Reduce prepositional phrase stacking: The phrase "performance based on record counts and # of tokens generated across tokenization and transformation activities" stacks multiple prepositional phrases. Simplify to: "We measured performance by counting records and tokens during tokenization and transformation."
Plain Language: Needs Attention - Phrases like "discernible grouping," "discrepancy between warehouse sizes," and "consistently similar trend" use unnecessarily complex vocabulary. Use "clear patterns," "differences," and "similar pattern" instead.
Sentence Length: Flagged - Several sentences exceed 25 words:
- "Smaller warehouse sizes may be adequate and more cost-effective for lower-scale workloads (100K rows), but as the scale increases, larger warehouses still provide better performance and scalability, especially for tokenization." (31 words)
- "For all below cases that use a desktop comparison, we tested locally using an M3 Mac with 32 GB of RAM using 10 cores for processing." (26 words)
- "These improvements range from 9x speed improvements at the lowest level to 14x in the most optimal scenario." (17 words but could be clearer)
Jargon: Needs Attention - Multiple unexplained technical terms:
- "Snowflake polars package" (not explained)
- "tokenization" (used extensively without definition)
- "transformation" (used without context)
- "XL," "2XL" warehouse designations (abbreviations not spelled out)
- "native integration" (not explained)
Active Voice: Flagged - Several passive constructions found:
- "We conducted thorough performance testing" (active - good)
- "Number of Tokens Being Tokenized/Transformed" (passive gerund)
- "We assessed performance based on..." (active - good)
- Most of the article uses active voice appropriately
Heading Clarity: Needs Attention - The table heading "Number of Tokens Being Tokenized/Transformed Medium or Large Standard Warehouse XL or 2XL Standard Warehouse Snowflake Optimized XL Warehouse" appears to be garbled or improperly formatted. It needs clear structure and proper punctuation or table formatting.
Link Text: Cannot Assess - No hyperlinks present in the provided text.
Abbreviations: Flagged - Unexplained abbreviations:
- "XL" and "2XL" (warehouse sizes not spelled out on first use)
- "GB" (likely understood but not defined)
- "M3 Mac" (brand-specific abbreviation)
- "#" used instead of "number of" in heading
Overall WCAG Writing Score: Needs Attention
1. Break down complex compound sentences: The sentence "Gold and Silver partners benefit from enhanced visibility across the ecosystem in the Ecosystem Explorer page" (16 words) combines multiple concepts. Split into: "Gold and Silver partners get more visibility. They appear in the Ecosystem Explorer page."
2. Simplify multi-concept sentences: "These partners are experienced in exchanging health data, and are proactive in making it easy for partners to connect with them" (20 words). Break into shorter, clearer statements: "These partners are experienced in exchanging health data. They make it easy for other partners to connect with them."
3. Clarify the points system explanation: The sentence "Partner status is attained through a points system based on a combination of three factors: Links (into or out of your organization) Integration with Datavant Switchboard" runs together concepts. Restructure with bullets and simpler language: "You earn partner status through points. We award points for three things:" then list each factor on its own line with brief explanation.
Plain Language: Needs Attention - Terms like "elevate the status and visibility," "ecosystem," and "proactive" are unnecessarily complex. Use simpler alternatives: "increase recognition," "network," and "quick to respond."
Sentence Length: Pass - Most sentences are under 25 words. Longest is 23 words.
Jargon: Needs Attention - Multiple unexplained technical terms:
- "Ecosystem Explorer page" (not defined)
- "Switchboard" (product name not explained)
- "On Demand for overlaps" (technical term not explained)
- "Datavant Tokens" (not defined for new users)
Active Voice: Needs Attention - Passive constructions found:
- "Partner status is attained" → Change to "Partners attain status" or "You earn partner status"
- "Gold Status is attained based on" → Change to "You attain Gold Status by"
Heading Clarity: Needs Attention - Only one heading provided. Article would benefit from subheadings like "How to Earn Partner Status," "Point System Explained," and "Status Updates."
Link Text: Cannot assess - No link text provided in cleaned prose.
Abbreviations: Needs Attention - "Q4 2021" should be written as "Quarter 4 of 2021" on first use, or explain "Q4 (fourth quarter)."
Overall WCAG Writing Score: Needs Attention
1. Break down complex compound sentences
Example: "This report can be especially useful when evaluating mortality tables (or other tables of a similar data type) when you want to build the largest possible cohort or pool of data."
Suggested revision: "This report is useful when evaluating mortality tables. Use it when you want to build the largest possible cohort or pool of data."
2. Simplify multi-clause explanatory sentences
Example: "In some cases, you may need to build the largest possible pool of data that also overlaps with a specific cohort of interest."
Suggested revision: "Sometimes you need a large pool of data. This data must also overlap with a specific cohort."
3. Reduce sentence complexity in procedural steps
Example: "In the Select Output Columns step, select which output columns should be preserved in the resulting overlap segment."
Suggested revision: "In the Select Output Columns step, choose the columns to keep in your overlap segment."
Plain Language: Needs Attention
- "real-time deduplication" - technical term not explained
- "cohort or pool of data" - business jargon could be simplified
- "retrospective study" - medical term not defined
Sentence Length: Pass with caution
Most sentences are under 25 words, though some approach the limit. The average of 23 words per sentence is acceptable but on the high side.
Jargon: Needs Attention
Unexplained technical terms found:
- "deduplication"
- "cohort" (used extensively without definition)
- "tokens" (mentioned without explanation)
- "retrospective study"
- "mortality sources"
- "Segment Builder" (product name, acceptable)
Active Voice: Pass
Most instructions use active voice appropriately ("select," "create," "follow"). Some passive constructions exist but are acceptable: "are represented," "should be preserved."
Heading Clarity: Pass
"Step 1. Create overlapping segments" is clear and descriptive. Article follows logical structure.
Link Text: Pass
No vague link text detected. Reference to "Segment Builder User Guide" is descriptive.
Abbreviations: Pass
No unexplained abbreviations found. "WCAG" is not in the article text.
Overall WCAG Writing Score: Needs Attention
While the score is only slightly above the Grade 12 target, here are specific improvements to make the content more accessible:
1. Break down compound technical phrases: Change "Register your tokenized data" to "Register your data tokens" and "Save transformed tokens for partner" to "Save the transformed tokens to send to your partner." Simpler phrasing reduces cognitive load.
2. Add transitional explanations between code blocks: Before each SQL code snippet, add a brief plain-language sentence explaining what will happen. For example: "This command registers your patient token table so it can be referenced in the next step."
3. Simplify the directional language: The phrases "Transform from your site to partner's site (direction = 'to')" and "Transform from partner's site to your site (direction = 'from')" are conceptually dense. Rewrite as: "Transform tokens to send to your partner (direction = 'to')" and "Transform tokens you received from your partner (direction = 'from')."
Plain Language: Needs Attention - Technical terms like "tokenized data," "persistent," "secure share," and "RESULT_SCAN" appear without explanation. Consider adding a brief glossary or inline definitions.
Sentence Length: Pass - Most sentences are concise. The breakdown shows average sentence length of 7.1 words, well below the 25-word threshold.
Jargon: Needs Attention - Unexplained technical terms include:
- "tokenized data"
- "persistent"
- "secure share"
- "stage"
- "RESULT_SCAN"
- "LAST_QUERY_ID()"
Active Voice: Pass - Instructions use clear imperative voice (Register, Transform, Save, Export, Load, Verify).
Heading Clarity: Good - Step-by-step numbered headings are clear and action-oriented. Consider adding a summary sentence after "Overview" to preview what users will accomplish.
Link Text: N/A - No links present in the provided text.
Abbreviations: Needs Attention - "SQL" is implied but not explicitly mentioned or explained. "CSV" appears without expansion on first use.
Overall WCAG Writing Score: Needs Attention
The article has excellent structure with clear step-by-step instructions and concise sentences, but would benefit from brief explanations of technical terms and abbreviations to serve users with varying expertise levels.
The content exceeds the Grade 12 target. Here are three specific suggestions to improve readability:
1. Break down complex compound sentences: The sentence "Sharing a data table allows you to give a partner permission to interact with it using Datavant products (e.g. Assess and Segment Builder)." could be split: "You can share a data table with a partner. This gives them permission to interact with it using Datavant products (e.g. Assess and Segment Builder)."
2. Simplify technical explanations: The sentence "The only way for a customer to view your data is 1) via a distribution that is approved by you and manually set up by Datavant or 2) you send them your data directly outside of the Datavant Connect Platform" could become: "A customer can only view your data in two ways: 1) Through a distribution you approve that Datavant sets up, or 2) If you send them data directly outside Datavant Connect Platform."
3. Reduce nested clauses: The sentence "Third-party permissions will be subject to your organization's blocklist plus any additional companies or industries you choose to block for this share" could be: "Third-party permissions follow your organization's blocklist. You can also block additional companies or industries for this specific share."
Plain Language: Needs Attention - Contains phrases like "metadata becomes visible," "relevant permissions," and "subject to your organization's blocklist" that could be simplified for broader comprehension.
Sentence Length: Needs Attention - Several sentences exceed 25 words:
- "The only way for a customer to view your data is 1) via a distribution that is approved by you and manually set up by Datavant or 2) you send them your data directly outside of the Datavant Connect Platform." (40 words)
- "Note this will only allow exporting of the partner's tokens that overlap with your table – no partner will have access to your tokens or any additional data in the table via this workflow." (34 words)
- "Third-party permissions will be subject to your organization's blocklist plus any additional companies or industries you choose to block for this share." (25 words)
Jargon: Needs Attention - Several technical terms lack explanation:
- "Tokens" (used frequently but not defined until mentioned parenthetically)
- "Metadata"
- "Profile report"
- "Segment"
- "Blocklist"
Active Voice: Pass - Most content uses active voice effectively ("Click Share," "Choose the Permissions," "go to the My Data page").
Heading Clarity: Pass - Headings are descriptive and clearly indicate content ("Sharing a Single Table or Segment," "Sharing a Table and/or Segment in Bulk").
Link Text: Pass - No vague "click here" links detected in the text provided.
Abbreviations: Pass - "e.g." is commonly understood; no other unexplained abbreviations found.
Overall WCAG Writing Score: Needs Attention
The content is slightly above the Grade 12 target. Here are three specific suggestions to reduce complexity:
1. Break down long, multi-clause sentences into shorter ones. For example:
- Current: "A data dictionary should have a meaningful description of each variable, with that description matching how the data is as we see it within the table(s) provided, rather than as it was at some earlier stage."
- Suggested: "A data dictionary should have a meaningful description of each variable. The description must match the current data in the tables we receive, not how it appeared at an earlier stage."
2. Simplify complex sentence structures with multiple conditions. For example:
- Current: "If the data is more than 1 million patients, we require a sample of 1 million patients or 10% of the data (whichever is larger)"
- Suggested: "For datasets over 1 million patients: provide either 1 million patients OR 10% of the data. We need whichever option is larger."
3. Use bullet points or numbered lists to present conditional information instead of embedding it in paragraph form. The data sample size requirements would be clearer as a simple list rather than flowing narrative text with multiple "if" statements.
Plain Language: Needs Attention - Several instances of unnecessarily complex phrasing:
- "expedite the expert determination process" could be "speed up the process"
- "at the outset" could be "at the start"
- "it may also be suitable to" could be "you can also"
- "prescriptive around specific sample sizes" could be "specific about sample sizes"
Sentence Length: Needs Attention - Several sentences exceed 25 words:
- "Presenting the data and other information consistent with the specifications given will expedite the expert determination process." (17 words - Pass)
- "A data dictionary should have a meaningful description of each variable, with that description matching how the data is as we see it within the table(s) provided, rather than as it was at some earlier stage." (38 words - Too long)
- "For smaller sets of data, it may also be suitable to make the full set of data available to us, and we can then review the data and perform sampling ourselves to ensure that the sample generated is representative and suitably linked across tables." (50 words - Too long)
Jargon: Needs Attention - Several technical terms lack definition or context:
- "expert determination" (appears multiple times, never defined)
- "pipe delimited" (technical file format, no explanation)
- "parquet file format" (technical file format, no explanation)
- "ED" (abbreviation used in asterisk note)
Active Voice: Good - Most sentences use active voice effectively. One minor passive construction: "Our analysis is typically performed on data tables" (could be "We typically perform our analysis on data tables")
Heading Clarity: Good - The title clearly describes the article content
Link Text: Needs Attention - Two instances of vague link text:
- "please see here" (should describe the destination, e.g., "see our Data Dictionary Requirements guide")
- "see our Sampling Guidelines" (this one is acceptable as it names the destination)
Abbreviations: Needs Attention:
- "ED" appears in the asterisk note without being spelled out (likely "Expert Determination" based on context)
- ".csv", ".json" - file extensions are acceptable as standard technical terms
Overall WCAG Writing Score: Needs Attention
The article has good structure and mostly active voice, but would benefit from shorter sentences, simpler language, defined technical terms, and clearer link text to improve accessibility for all readers.
1. Break down complex noun phrases into simpler constructions
- Current: "Datavant's maintenance policy for the Datavant Tokenization application and deployments"
- Suggested: "How Datavant maintains the Tokenization application"
2. Simplify technical explanations with shorter, more direct phrasing
- Current: "Any proxy server passes through the incoming SSL certificate from Datavant's endpoints, rather than replacing it with a self-signed certificate."
- Suggested: "Your proxy server must pass through SSL certificates from Datavant. It must not replace them with self-signed certificates."
3. Use bulleted lists to break up dense information clusters
- Current: "It checks DNS resolution, TCP connectivity, and SSL/TLS validation to confirm that your machine can reach the required services."
- Suggested: Transform into a bulleted list: "It checks three things: DNS resolution, TCP connectivity, and SSL/TLS validation"
Plain Language: Needs Attention - Contains unexplained technical concepts like "pass-through mode," "hash salt," "encryption keys," and "transit key" without context.
Sentence Length: Pass - Most sentences are under 25 words, though one sentence at 26 words could be shortened: "Any proxy server passes through the incoming SSL certificate from Datavant's endpoints, rather than replacing it with a self-signed certificate."
Jargon: Needs Attention - Multiple unexplained technical terms: "hash salt," "transit key," "connect key," "pass-through mode," "self-signed certificate," "DNS resolution," "TCP connectivity," "SSL/TLS validation"
Active Voice: Pass - Generally uses active voice well throughout the document.
Heading Clarity: Pass - Headings are descriptive and well-structured (Overview, Compatible Operating Systems, Network Connectivity, etc.)
Link Text: Pass - No vague link text detected; references are specific (e.g., "Client Versions and Support Policy," "Network Errors and Diagnostics Mode")
Abbreviations: Needs Attention - Several abbreviations lack first-use expansion: CLI (appears in title without expansion), SSL, TLS, TCP, DNS, HTTPS, AWS
Overall WCAG Writing Score: Needs Attention
The content is above the Grade 12 target. Here are 3 specific suggestions to improve readability:
1. Break down complex sentences with multiple clauses. For example: "If data sources have an existing relationship with Datavant where they are able to onboard their data to Portal directly, the most efficient approach is to have each source onboard their data individually, and Privacy Solutions will group the data together once everyone has onboarded." This 44-word sentence should be split: "Does your data source have an existing relationship with Datavant? If yes, have each source onboard their data individually. Privacy Solutions will then group the data together."
2. Simplify technical phrasing. Replace "anticipated recipient" with "intended recipient" and "issues from arising during the project" with "project delays" to reduce syllable count and improve clarity.
3. Use shorter, more direct answers. The tokenization answer contains nested conditional clauses. Simplify to: "Do you need to tokenize? Yes, if you're providing tokenized data to the recipient. No, if you're only providing non-tokenized attributes and not linking data with tokens."
Plain Language: Needs Attention - Terms like "onboarding," "tokenize," "linking schema," and "Expert Determination" are used in specialized ways without plain language alternatives or definitions.
Sentence Length: Flagged - Multiple sentences exceed 25 words:
- "If data sources have an existing relationship with Datavant where they are able to onboard their data to Portal directly, the most efficient approach is to have each source onboard their data individually, and Privacy Solutions will group the data together once everyone has onboarded." (44 words)
- "To ensure the data scientists have all the information they need for a smooth analysis, the ideal data dictionary includes the ones previously mentioned, plus variable data type, variable length, example values, references to code sets, and mapping files." (41 words)
Jargon: Flagged - Unexplained technical terms include:
- "data dictionary" (later partially explained)
- "tokenize/tokenized/tokens"
- "onboarding/onboard" (used as technical jargon)
- "Expert Determination"
- "linking schema"
- "common identifier"
- "Portal" (appears to be a product name without context)
Active Voice: Pass - Most content uses active voice appropriately ("Reach out to," "let your Customer Success Lead know").
Heading Clarity: Pass - Q&A format is clear, though "General" could be more descriptive (e.g., "General Access and Setup").
Link Text: Cannot assess - No links present in the cleaned prose text provided.
Abbreviations: Flagged - "FAQs" in title is not spelled out on first use; "ID" used without definition.
Overall WCAG Writing Score: Needs Attention
While the score of 12.9 is very close to the target threshold, it still exceeds Grade 12. Here are three specific suggestions to bring it below 12:
1. Break down compound sentences with multiple clauses:
- Current: "Creates transit tokens by transforming tokens from a site-specific encryption key into a transit encryption key that is unique to both the sender and the intended recipient."
- Suggested: "Creates transit tokens. This transforms tokens from a site-specific encryption key. The new transit encryption key is unique to both the sender and recipient."
2. Simplify technical definitions:
- Current: "Datavant's tokenization software generates tokens, or de-identified patient keys, using different combinations of patient demographic information such as name, date of birth, administrative gender, and social security number."
- Suggested: "Datavant's tokenization software creates tokens (de-identified patient keys). It uses patient information like name, date of birth, gender, and social security number."
3. Reduce nested explanatory phrases:
- Current: "Transform tokens for use within Datavant tools such as Assess, Ecosystem Explorer, Segment Builder, Match, or Distribution."
- Suggested: "Transform tokens for Datavant tools. These tools include Assess, Ecosystem Explorer, Segment Builder, Match, and Distribution."
Plain Language: Needs Attention
- Phrases like "transit encryption key that is unique to both the sender and the intended recipient" and "site-specific encryption key derived from patient demographics" are complex
- Consider defining "transit tokens" and "site-specific tokens" earlier with simpler language
Sentence Length: Pass
- Average of 18.1 words per sentence is well within acceptable range
- No sentences appear to significantly exceed 25 words
Jargon: Needs Attention
- "Tokenizing" - explained with context
- "First-party data" - not explained
- "Transit tokens" - used before clear definition
- "Site-specific encryption key" - technical term not simplified
- "De-identification operations" - not explained
- "PII" - abbreviation used but not defined on first use
Active Voice: Pass with minor flags
- Most content uses active voice effectively
- One passive construction: "These functions are carried out through three core operations" (could be: "Three core operations carry out these functions")
Heading Clarity: Pass
- Headings are descriptive and hierarchical
- "About the Datavant Tokenization Software" clearly introduces the topic
- "Tokenize and transform" effectively summarizes the section content
Link Text: Needs Attention
- "see the General Onboarding User Guide" - acceptable but generic
- "see Defining the Configuration Output Operations" - acceptable
- Consider making link text more descriptive of what users will find
Abbreviations: Needs Attention
- "CLI" - explained in context (Command Line Interface implied)
- "PII" - used in heading "Creating Tokens from PII" but never defined (should be "Personally Identifiable Information")
Overall WCAG Writing Score: Needs Attention
The article has good structural elements and reasonable sentence length, but would benefit from defining technical terms more clearly, explaining all abbreviations on first use (especially PII), and simplifying complex technical phrases for broader accessibility.
The content is slightly above the Grade 12 target. Here are three specific suggestions:
1. Break down complex sentences with multiple clauses. For example: "If you add companies or industries to a Table Blocklist, any users from that company or from companies belonging to that industry will be unable to view or interact with the table at all." could become two sentences: "You can add companies or industries to a Table Blocklist. Users from those companies or industries will be unable to view or interact with the table."
2. Simplify the parenthetical information. The phrase "you can view various attributes of the table including high level table details, AWS Catalog information, and data use approvals settings for the table" is repetitive and dense. Simplify to: "you can view table attributes such as details, AWS Catalog information, and data use approval settings."
3. Clarify the blocklist/allowlist explanation. The example starting with "Example: if you list IndustryA on your organization blocklist..." appears incomplete in the text and uses abstract placeholders. Use concrete phrasing: "Your blocklist always takes priority. A company on your blocklist cannot access the table, even if you add them to your allowlist."
Plain Language: Needs Attention - Terms like "pre-sales feasibility assessments," "dataset evaluations," and "discoverable" could be simplified or better explained in context.
Sentence Length: Needs Attention - Several sentences exceed 25 words:
- "If you add companies or industries to a Table Blocklist, any users from that company or from companies belonging to that industry will be unable to view or interact with the table at all." (33 words)
- "The solution enables pre-sales feasibility assessments and dataset evaluations through the Datavant Connect Web Platform, while ensuring that all data remains securely within each source's AWS environment." (28 words)
Jargon: Needs Attention - Multiple unexplained terms: "AWS Catalog," "Assess product capability," "Profile or Overlap reports," "discoverable," "schema," "metadata"
Active Voice: Pass - Most sentences use active voice appropriately. Minor issue: "Tables registered with AWS are only available" could be "You can only use AWS registered tables"
Heading Clarity: Pass - Headings are clear and descriptive (e.g., "Update Data Use Approvals," "Update a Table Blocklist")
Link Text: Cannot assess - No link text present in cleaned prose version
Abbreviations: Needs Attention - "AWS" is used throughout without initial expansion (should be "Amazon Web Services (AWS)" on first use)
Overall WCAG Writing Score: Needs Attention
While the score of 12.8 is close to the Grade 12 target, it slightly exceeds the recommended threshold. Here are three specific improvements:
1. Break down long technical sentences: The opening sentence contains 32 words: "This article includes information that relates to Datavant CLI v5, which is available on limited release. All CLI-specific information is highlighted in purple callout boxes." Consider splitting: "This article covers Datavant CLI v5. CLI v5 is available on limited release. Look for CLI-specific information in purple callout boxes."
2. Simplify conditional phrasing: The sentence "If you're tokenizing using the Desktop Application, you may select tokenizing identified data and transforming tokens to send to a partner, which generates both a tokenized and transformed output in a single workflow" (31 words) is complex. Simplify to: "Desktop Application users can tokenize and transform data in one workflow. This creates both outputs at once."
3. Use shorter introductory statements: Instead of "When using the Datavant CLI in batch, server, or streaming mode, you must enter commands in the CLI to run tokenize and transform," try: "Batch, server, and streaming modes require CLI commands. You run tokenize and transform separately."
Plain Language: Needs Attention - Some sentences use unnecessarily complex constructions. Example: "which generates both a tokenized and transformed output in a single workflow" could be "which creates both outputs at once."
Sentence Length: Flagged - Several sentences exceed 25 words:
- Opening sentence about CLI v5 and purple callout boxes (32 words)
- Sentence about Desktop Application tokenizing process (31 words)
- Sentence about running CLI commands in different modes (24 words, borderline)
Jargon: Needs Attention - Several technical terms lack explanation for new users:
- "tokenize" and "transform" (used extensively without initial definition)
- "batch mode," "server mode," "streaming mode" (mentioned but not explained)
- "CLI" (Command Line Interface - abbreviated in title but not spelled out)
- "credentials file" (assumed knowledge)
- "pipe command" (| symbol not explained)
Abbreviations: Flagged:
- "CLI" - used throughout but never spelled out as "Command Line Interface"
- "OS" - spelled out once as "operating system" but could be clearer earlier
- "v5" - version abbreviation, acceptable in context
Active Voice: Pass - Most instructions use active voice appropriately ("enter commands," "run tokenize," "select tokenizing")
Heading Clarity: Pass - Headings clearly indicate OS and command type (e.g., "Mac, tokenize" and "Windows, transform-tokens to"). However, consider adding a brief heading before the command examples like "Command Structure by Operating System" for better navigation.
Link Text: Cannot assess - The cleaned prose text doesn't show the actual link text formatting, though references like "see Use Datavant CLI in Server Mode" appear descriptive rather than generic "click here" links.
Overall WCAG Writing Score: Needs Attention
The article has good structural elements but needs work on plain language, sentence length reduction, and upfront definition of technical terms to be fully accessible to all users.
While the score of 12.8 is close to the Grade 12 target, it slightly exceeds the recommended threshold. Here are three specific suggestions:
1. Break down complex conditional sentences: The sentence "If you maintain separate testing and production environments: Datavant can be deployed in both, allowing you to validate your setup end-to-end before running production jobs" could be split into two simpler statements: "Do you maintain separate testing and production environments? Deploy Datavant in both environments. This allows you to validate your setup end-to-end before running production jobs."
2. Simplify multi-clause explanations: The sentence "In addition to creating additional overhead and maintenance costs, using separate sites or configurations for testing does not improve testing outcomes, since the key variable for testing quality is whether your test data accurately represents the data you expect to process in production" is 43 words long. Break it into: "Using separate sites or configurations creates extra overhead and maintenance costs. It also does not improve testing outcomes. Testing quality depends on one key factor: whether your test data represents your production data."
3. Reduce nominalization: Change "tokenization application deployments" to "deploying tokenization applications" and "Optional arguments (input data encoding)" to "Optional: specify input data encoding"
Plain Language: Needs Attention - Phrases like "native test mode," "tokenization application deployments," "end-to-end," and "key variable for testing quality" could be simplified. Use "built-in" instead of "native," "deploy tokenization applications" instead of "application deployments."
Sentence Length: Flag - One sentence exceeds 25 words significantly:
- "In addition to creating additional overhead and maintenance costs, using separate sites or configurations for testing does not improve testing outcomes, since the key variable for testing quality is whether your test data accurately represents the data you expect to process in production." (43 words)
Jargon: Needs Attention - Several technical terms lack explanation:
- "tokenization" (first use should be briefly explained)
- "token transformation"
- "transit key transformation"
- "connect key transformation"
- "synthetic datasets"
- "encoding"
Active Voice: Pass - Most content uses active voice appropriately ("Datavant does not provide," "confirm that," "Run your test command")
Heading Clarity: Pass - Headings are clear and action-oriented ("Validate Input and Output Data," "Test the Command," "Recommended Testing Workflow")
Link Text: Pass - Link text is descriptive ("Download Test Input File" clearly indicates destination)
Abbreviations: Needs Attention
- "vs." appears twice without being spelled out on first use
- "prod" should be "production" on first use
- "e.g." should be "for example" or spell out "exempli gratia"
Overall WCAG Writing Score: Needs Attention
While close to the target threshold, this content would benefit from simplification to reach Grade 12 or below:
1. Break down complex sentences with multiple clauses: The sentence "Others are more complex, requiring coordination across multiple organizations and a longer project lifecycle" (16 words) uses participial phrases that add complexity. Simplify to: "Others are more complex. They require coordination across multiple organizations. They have a longer project lifecycle."
2. Reduce multi-syllable word density: Terms like "organizations" (5 syllables), "coordination" (5 syllables), and "tokenization" (5 syllables) cluster together. Where possible, use shorter alternatives: "groups" instead of "organizations" (when contextually appropriate), or add brief explanations after complex terms.
3. Simplify the opening concept: "Datavant products support organizations at every stage of their data matching and linking journey" contains abstract terminology. Rephrase to: "Datavant products help organizations match and link data. They work at every stage of your project."
Plain Language: Needs Attention - Several abstract phrases reduce clarity: "data matching and linking journey" (journey is metaphorical), "project lifecycle" (lifecycle is jargon), and "coordination across multiple organizations" (bureaucratic phrasing).
Sentence Length: Pass - All sentences are under 25 words. Longest sentence is 22 words.
Jargon: Needs Attention - "tokenization" appears without explanation. "Clinical research network tokenization" is presented as a project type but users may not understand what tokenization means in this context.
Active Voice: Pass - Most content uses active voice effectively ("Log in to...", "select Project Dashboard", "Datavant has created").
Heading Clarity: Pass - Headings are clear and action-oriented: "Access the Project Dashboard" and "Additional Resources by Project Type" tell users exactly what to expect.
Link Text: Needs Attention - "guide coming soon!" is not actually a link but reads like placeholder text that should be removed or updated with actual link when available.
Abbreviations: Pass - No unexplained abbreviations found in the text.
Overall WCAG Writing Score: Needs Attention
The content is just above the Grade 12 target at 12.7. Here are three specific suggestions to bring it down:
1. Break down complex sentences with multiple clauses. For example: "Onboarding certain Profile Model fields to the Datavant Connect platform, along with tokens, unlocks extra capabilities" could become: "You can onboard Profile Model fields to the Datavant Connect platform. When you include tokens, this unlocks extra capabilities."
2. Simplify technical noun phrases. Replace "tables must contain only the variables listed in the Profile Model (or a subset of them) and all required remediations must be applied" with "Tables must contain only Profile Model variables. You can use all variables or a subset. You must apply all required remediations."
3. Use shorter, more direct sentences in the steps. For example: "Review the Profile Model Expert Determination summary document (linked at the end of this guide) to identify which data formats are accepted" becomes two sentences: "Review the Profile Model Expert Determination summary document. Use it to identify which data formats are accepted. Find the link at the end of this guide."
Plain Language: Needs Attention
- "Expert Determination" is used extensively without initial explanation
- "de-identified under HIPAA" assumes knowledge of regulatory context
- "granular Assess reports" uses product-specific jargon without definition
- "auto-certification" is not explained before use
Sentence Length: Pass
Most sentences are under 25 words. The average of 17.1 words per sentence is good.
Jargon: Needs Attention
Unexplained technical terms include:
- HIPAA
- Expert Determination
- tokens/tokenized
- Datavant Connect platform
- Assess reports (appears to be a product name)
- Match performance
- PHI (appears later without definition)
- Zip3
- ICD-10, NDC, CPT HCPCS (medical coding systems)
Active Voice: Needs Attention
Passive constructions found:
- "has been certified as de-identified"
- "are provided in the Profile Model"
- "are available to provide flexibility"
- "is only considered de-identified"
- "if PHI is placed in these fields"
Heading Clarity: Pass
Headings are clear and descriptive (Overview, Profile Model fields, How to Use the Profile Model, Step 1, Step 2, Step 3).
Link Text: Needs Attention
- "email support@datavant.com" - functional but could be more descriptive (e.g., "email support to request the full certification")
- Multiple references to "linked at the end of this guide" or "at the end of this article" without actual visible links in the cleaned text
Abbreviations: Needs Attention
Unexplained abbreviations:
- HIPAA (not spelled out on first use)
- ICD-10
- NDC
- CPT
- HCPCS
- PHI (appears without definition)
Overall WCAG Writing Score: Needs Attention
The article has good structure and reasonable sentence length, but requires glossary support or inline definitions for technical terms, abbreviations, and regulatory concepts. Converting passive voice to active and providing context for specialized terminology would significantly improve accessibility.
The score of 12.7 slightly exceeds the Grade 12 target for technical documentation. Here are three specific suggestions:
1. Break down complex sentences with multiple clauses: The sentence "While Datavant performs some basic format checks on the fields that are processed, some fields (e.g. clinical values) may be configured to pass through without modification" (25 words) could be split: "Datavant performs some basic format checks on processed fields. However, some fields (e.g. clinical values) may be configured to pass through without modification."
2. Simplify technical explanations: The sentence "The Safe Harbor provision requires that there be a total population of greater than 20k individuals within the 3-digit ZIP Code Tabulation Area (ZCTA) as determined by U.S. Census data from the most recent Decennial Census" (34 words) could be shortened: "Safe Harbor requires a total population greater than 20k individuals within the 3-digit ZIP Code Tabulation Area (ZCTA). This is determined by the most recent U.S. Decennial Census."
3. Use simpler vocabulary where possible: Replace "remediations" with "changes" or "modifications" in early mentions, or define it immediately in the first sentence rather than in the second sentence.
Plain Language: Needs Attention - Heavy use of specialized terminology ("remediations," "tokenization," "de-identified," "Expert Determination," "Safe Harbor") without immediate definitions. The term "remediation" is defined in the second sentence but could be clearer.
Sentence Length: Needs Attention - Several sentences exceed 25 words:
- "While Datavant performs some basic format checks... into the output file." (34 words)
- "The Safe Harbor provision requires... most recent Decennial Census." (34 words)
- "Therefore, it is possible that incorrectly placing PHI values... into the output file." (20 words, acceptable)
Jargon: Needs Attention - Multiple unexplained terms:
- PII (explained as "personally identifiable information" ✓)
- HIPAA (not explained)
- PHI (not explained, different from PII)
- ZCTA (explained as "ZIP Code Tabulation Area" ✓)
- ICD9/ICD10 codes (not explained)
- ZIP3 (not explained)
- Null/Nulls (technical database term, not explained for general users)
Active Voice: Needs Attention - Several passive constructions:
- "may be configured to pass through" → "you can configure to pass through"
- "this is done by clicking" → "click the trash icon"
- "is replaced with NULL" → "the system replaces it with NULL"
Heading Clarity: Pass - "Overview" and "Output Operations" are clear structural headings.
Link Text: Cannot assess - No link text present in cleaned prose.
Abbreviations: Needs Attention - Several abbreviations not expanded on first use:
- HIPAA (not expanded)
- PHI (not expanded)
- ICD (not expanded)
- ZIP3 (not explained as "first 3 digits of ZIP code")
Overall WCAG Writing Score: Needs Attention
The article would benefit from: defining all acronyms on first use, breaking longer sentences into shorter ones, explaining database terminology like "null" for non-technical users, and converting passive voice to active voice throughout.
The content is slightly above the Grade 12 target. Here are three specific suggestions:
1. Break down complex sentences with multiple clauses - Example: "If a larger warehouse is needed, the XL is generally still the clear choice, as the 2XL performs consistently in between Large and 2XL warehouses, but doesn't fall off as hard as 2XL." Break this into: "If you need a larger warehouse, choose XL. The 2XL performs between Large and XL warehouses. However, the 2XL maintains more consistent performance than the XL under heavy loads."
2. Simplify technical descriptions - Example: "Post-Polars implementation showed a sizable boost in performance across all token counts, as well as a stabilization in larger token counts in smaller datasets." Simplify to: "After implementing Polars, performance improved across all token counts. Larger token counts in smaller datasets also became more stable."
3. Use bullet points for specification details - The paragraph starting "We recommend the use of a medium or large warehouse..." contains multiple nested recommendations. Convert these to a bulleted list or table for easier scanning.
Plain Language: Needs Attention - Several instances of unnecessarily complex phrasing: "conducted thorough performance testing" (use "tested"), "discernible grouping" (use "clear grouping"), "sizable boost" (use "significant improvement").
Sentence Length: Pass - Most sentences stay under 25 words. One borderline example at 28 words: "If a larger warehouse is needed, the XL is generally still the clear choice, as the 2XL performs consistently in between Large and 2XL warehouses, but doesn't fall off as hard as 2XL."
Jargon: Needs Attention - Several terms lack context or explanation:
- "Polars" (not explained what this is)
- "tokenization" vs "transformation" (assumed knowledge)
- "Snowflake Optimized Warehouses" (not defined)
- "2XL performs consistently in between Large and 2XL" (confusing comparison)
Active Voice: Pass - Generally uses active voice well ("We conducted," "We recommend," "We assessed").
Heading Clarity: Needs Attention - The article appears to lack clear section headings in the provided text. The table header "Number of Tokens Being Transformed/Tokenized" is present but difficult to parse. Recommend adding headings like "Warehouse Recommendations by Dataset Size" and "Performance Test Results."
Link Text: Cannot assess - No links provided in the cleaned prose text.
Abbreviations: Needs Attention -
- "XL" and "2XL" - not spelled out on first use
- "GB" and "RAM" - not spelled out
- "1m" vs "1 million" - inconsistent usage
Overall WCAG Writing Score: Needs Attention
The content exceeds the Grade 12 target and should be simplified. Here are three specific suggestions:
1. Break down complex compound sentences: The sentence "When transformed, these tokens are called transit tokens are unique to the two sites they connect" contains a grammatical error and packs too much information. Revise to: "When transformed, these tokens are called transit tokens. Transit tokens are unique to the two sites they connect."
2. Simplify technical explanations: The phrase "To successfully run transform-tokens, a connect key or a transit key must first be provisioned by Datavant between two sites" uses passive voice and complex structure. Revise to: "Before you run transform-tokens, Datavant must provision a connect key or transit key between the two sites."
3. Reduce clause complexity: The sentence "If you need to onboard tokens to the Datavant Connect platform, or if you need to use Assess, Match, Segment Builder, or Distribution, see General Onboarding User Guide" contains multiple nested clauses. Revise to: "Do you need to onboard tokens or use Assess, Match, Segment Builder, or Distribution? See the General Onboarding User Guide."
Plain Language: Needs Attention - Contains unexplained technical phrases like "site-specific tokens," "transit tokens," and "provisioned" without clear definitions in context.
Sentence Length: Pass - Most sentences are under 25 words, though some approach this limit.
Jargon: Needs Attention - Multiple unexplained technical terms:
- "site-specific tokens"
- "transit tokens"
- "connect key"
- "transit key"
- "provisioned"
- "transform-tokens"
- "tokenization"
- "SFTP"
- "S3"
Active Voice: Needs Attention - Several passive constructions found:
- "a connect key or a transit key must first be provisioned"
- "tokens are called transit tokens"
- "typically enabled by default"
- "partners are displayed"
Heading Clarity: Needs Attention - "Share Data Out" is informal; suggest "How to Share Data with Partners." "Data Sharing Requirements" could be "What You Need Before Sharing Data."
Link Text: Pass - Link references are descriptive (e.g., "General Onboarding User Guide," "Introduction to Encryption Keys").
Abbreviations: Needs Attention - Unexplained abbreviations:
- SFTP (first use)
- S3 (first use)
- CLI (mentioned but not expanded)
Overall WCAG Writing Score: Needs Attention
While the score of 12.5 is just slightly above the Grade 12 target, there is room for improvement. Here are three specific suggestions:
1. Break down complex opening sentence: The first sentence contains 23 words and multiple concepts. Change from: "The Datavant CLI and Datavant Desktop are unable to function without successfully connecting to a series of Datavant owned endpoints (sec.datavant.com; auth.datavant.com; api.datavant.com)." To: "The Datavant CLI and Datavant Desktop need to connect to Datavant endpoints to function. These endpoints include sec.datavant.com, auth.datavant.com, and api.datavant.com."
2. Simplify technical explanations: Change "If these resolutions are failing to produce an IP, or the IP addresses yielded are private..." to "If DNS cannot find an IP address, or if the IP address is private..."
3. Use shorter, direct instructions: Change "Provided the domain resolutions are valid, we then attempt a TCP handshake" to "After DNS resolution succeeds, the CLI attempts a TCP handshake."
Plain Language: Needs Attention - Several phrases use unnecessarily complex language: "invoked automatically," "surfaced in the test output," "resolutions are failing to produce," "IP addresses yielded are private"
Sentence Length: Flag - One sentence exceeds 25 words: "If your networking system relies on proxy servers to redirect traffic, please ensure that they are not obstructing the CLI from running." (23 words - close but acceptable). The opening sentence is 23 words but dense with technical concepts.
Jargon: Needs Attention - Several technical terms lack explanation: TCP handshake, TLS connection, DNS, pass-through mode, SSL certificate, self-signed certificate. While the audience is technical, brief explanations or links would improve accessibility.
Active Voice: Pass - Most instructions use active voice effectively ("We first check," "We recommend," "Ensure any proxy server")
Heading Clarity: Needs Attention - The article appears to lack clear section headings. Adding headings like "What is Diagnostic Mode?", "Running Diagnostic Mode," "Troubleshooting Steps," and "Contacting Support" would improve scannability.
Link Text: Pass - The reference to "Technical Requirements for On-Premise Software" is descriptive link text.
Abbreviations: Needs Attention - CLI, DNS, TCP, TLS, SSL, IP are used without first defining them (e.g., "Command Line Interface (CLI)," "Domain Name System (DNS)")
Overall WCAG Writing Score: Needs Attention
The content is close to the target threshold but could be improved with minor adjustments:
1. Simplify compound noun phrases: Replace phrases like "Configuration names are created based on the table names in your data dictionary" with shorter alternatives: "Configuration names come from table names in your data dictionary."
2. Break down complex conditional sentences: The sentence "If you are looking to create multiple configurations at once for tokenization and/or data onboarding, look no further!" contains multiple concepts. Simplify to: "Use this process to create multiple configurations at once. This works for tokenization and data onboarding."
3. Reduce prepositional phrase stacking: "Under Select what your example data contains, toggle on 'Upload a Data Dictionary to CSV to create multiple configurations in bulk'" has nested prepositional phrases. Revise to: "Find the 'Select what your example data contains' section. Toggle on 'Upload a Data Dictionary to CSV.'"
Plain Language: Needs Attention - Several phrases use unnecessarily complex constructions: "look no further" (idiomatic), "must conform to the following format" (could be "must follow this format"), "appended to this article" (could be "attached to this article").
Sentence Length: Needs Attention - Multiple sentences exceed 25 words:
- "If you are looking to create multiple configurations at once for tokenization and/or data onboarding, look no further!" (19 words - acceptable)
- "This article will walk you through how to create configurations in bulk rather than creating single configurations one by one, starting with a .csv Data Dictionary." (27 words - too long)
- "If you are onboarding data to receive an Expert Determination from Privacy Hub, refer to the Privacy Hub Data Upload User Guide if you need to tokenize your data or the Streamlined Privacy Hub Onboarding Flow if you do not need to tokenize your data and only need to onboard data for a Privacy Hub project." (59 words - significantly too long)
- "Under Select what your example data contains, toggle on 'Upload a Data Dictionary to CSV to create multiple configurations in bulk', and select the site that will host the configuration generated by a data dictionary." (37 words - too long)
Jargon: Needs Attention - Several technical terms lack explanation:
- "tokenization" (used multiple times, never defined)
- "data onboarding" (not explained)
- "Expert Determination" (not explained)
- "Data Dictionary" (not defined until used extensively)
- "configuration" (article references another guide but brief inline definition would help)
Active Voice: Pass - Most sentences use active voice effectively. One minor passive construction: "A sample file is appended to this article" (could be "We've attached a sample file").
Heading Clarity: Pass - Step-based headings are clear and action-oriented. Each heading describes the specific task.
Link Text: Needs Attention - Link references are descriptive but could be formatted as actual embedded links rather than title references (e.g., "refer to the What is a Configuration user guide" - unclear if this is a link or just a title mention).
Abbreviations: Needs Attention:
- ".csv" - defined by context but never spelled out as "comma-separated values"
- "CSV" appears in UI quote but not explained
Overall WCAG Writing Score: Needs Attention
The article has good structure and clear steps, but improvements are needed in sentence length (especially the 59-word sentence), technical term definitions, and plain language usage to meet WCAG 2.2 AAA writing guidelines.
The score of 12.2 is slightly above the Grade 12 target for technical writing. Here are three specific suggestions to reduce complexity:
1. Break down compound sentences with multiple clauses: The sentence "The Datavant Native App solution enables partners to tokenize and transform directly within their organization's Snowflake tenant" could be simplified to two sentences: "The Datavant Native App solution works within your Snowflake tenant. It lets you tokenize and transform data directly."
2. Simplify technical phrases: Replace "extend the private listing to your account" with "share the private listing with your account" and "download the app to your Snowflake instance" with "add the app to your Snowflake instance."
3. Reduce multi-syllable words where possible: Change "accompaniment" to "companion guide," "deployment" to "setup," and "adjust the Worksheet SQL queries accordingly" to "update the Worksheet SQL queries."
Plain Language: Needs Attention - Several phrases use unnecessarily complex language: "extend the private listing," "adjust the Worksheet SQL queries accordingly to reflect," "privileges to install the listing." Consider: "share the private listing," "change the SQL queries to match," "permissions to install the app."
Sentence Length: Pass - Most sentences are under 25 words. The average of 17.6 words per sentence is well within accessible range.
Jargon: Needs Attention - Multiple unexplained technical terms:
- "tokenize/tokenization" (used 8+ times, never defined)
- "de-identified data"
- "Snowflake tenant"
- "Snowflake instance"
- "private listing"
- "Worksheet SQL queries"
Consider adding a brief glossary or inline definitions for first use.
Active Voice: Pass - Most content uses active voice ("Click Get to download," "Provide the Snowflake Account Identifier," "Refer to Creating").
Heading Clarity: Needs Attention - "Step 2. Create a configuration (only if running tokenize)" uses unclear phrasing. Suggest: "Step 2. Create a configuration (for tokenization only)."
Link Text: Needs Attention - The phrase "refer back to The Datavant Tokenization Software User Guide" lacks context about what specific information users will find there.
Abbreviations: Needs Attention - "CLI" appears unexpanded. "SQL" appears but is industry-standard and likely understood by target audience.
Overall WCAG Writing Score: Needs Attention
The content is slightly above the Grade 12 target. Here are three specific suggestions to improve readability:
1. Break down complex compound sentences - Example: "When clicking into a specific table, you will find another level of data management where each table page includes four available tabs that offer various data table management" could become: "Click into a specific table. You will find a table page with four tabs. These tabs help you manage your data."
2. Simplify technical explanations - Example: "If your data changes such that a new configuration is needed (e.g. additional/removed data columns), you must create a new table and associate it with the new configuration" could become: "Does your data have new or removed columns? You will need to create a new table with a new configuration."
3. Use shorter, more direct phrasing - Example: "To make your tables visible to all Ecosystem partners and available for them to run Assess reports, you can provision the table to be On Demand" could become: "Want all Ecosystem partners to see and use your tables? Set the table to 'On Demand'."
Plain Language: Needs Attention - Contains complex phrases like "provision the table to be On Demand," "associate it with the new configuration," and "eligible sentences analysed" that could be simplified.
Sentence Length: Needs Attention - Several sentences exceed 25 words:
- "When clicking into a specific table, you will find another level of data management where each table page includes four available tabs that offer various data table management" (30 words)
- "To make your tables visible to all Ecosystem partners and available for them to run Assess reports, you can provision the table to be On Demand" (28 words)
- "If your data changes such that a new configuration is needed (e.g. additional/removed data columns), you must create a new table and associate it with the new configuration" (28 words)
Jargon: Needs Attention - Several technical terms lack explanation:
- "Incremental" (in context of update type)
- "provision" (used as a verb)
- "On Demand" vs "By Request"
- "Ecosystem partners"
- "active distributions"
Active Voice: Pass - Most sentences use active voice appropriately ("click the Edit button," "you can delete a table").
Heading Clarity: Pass - The article appears to have clear structural sections (Table Details, Files tab, etc.).
Link Text: Pass - References like "What is a Table, Segment, and Data Group?" and "Share a Table or Segment" are descriptive.
Abbreviations: Pass - "e.g." is used but is commonly understood; no unexplained acronyms present.
Overall WCAG Writing Score: Needs Attention
The content is marginally above the Grade 12 target (by 0.2 points), but improvements can still enhance accessibility:
1. Break down complex conditional sentences: The sentence "While Datavant performs some basic format checks on the fields that are processed, some fields (e.g. clinical values) may be configured to pass through without modification" contains multiple clauses. Simplify to: "Datavant performs basic format checks on processed fields. However, some fields (like clinical values) may pass through without modification."
2. Simplify compound warning statements: The sentence "Therefore, it is possible that incorrectly placing PHI values in these pass-through fields could result in leakage into the output file" uses passive-adjacent construction. Revise to: "Incorrectly placing PHI values in pass-through fields can leak data into the output file."
3. Reduce prepositional phrase chains: "If your Company Profile is visible and you would like to indicate to other partners you have loaded one or more complete data tables..." can become: "If your Company Profile is visible, you can show partners that you have complete data tables ready to distribute."
Plain Language: Needs Attention - Some bureaucratic phrasing found: "must be approved if the Distribution tool can be enabled for your use case" could be simplified to "must be approved for your project."
Sentence Length: Pass - While some sentences approach the limit, most stay under 25 words. The longest is manageable at approximately 35 words (the PHI leakage warning), but consider splitting it.
Jargon: Needs Attention - Several unexplained technical terms:
- "PHI values" (not defined on first use)
- "pass-through fields" (technical concept not explained)
- "remediations" (unclear in this context)
- "site keys" (not defined)
- "ingestion" (technical term not explained)
Abbreviations: Needs Attention - "PHI" is used without expansion on first use (should be "Protected Health Information (PHI)")
Active Voice: Needs Attention - Several passive constructions found:
- "Data must be onboarded" → "You must onboard data"
- "must be certified" → "You must certify data tables"
- "may be configured" → "Datavant may configure some fields"
- "can only be enabled by Datavant" → "Only Datavant can enable distributions"
- "Files will be distributed" → "The system distributes files"
Heading Clarity: Pass - Step-based headings are clear and follow a logical sequence. Consider making them more action-oriented (e.g., "Step 1: Onboard Data" instead of "Step 1. Onboard Data...")
Link Text: Pass - Link text appears descriptive ("Understanding Distributions," "General Onboarding User Guide," "Managing Users For Your Company")
Overall WCAG Writing Score: Needs Attention
The article would benefit most from defining technical terms on first use, converting passive voice to active voice, and simplifying complex warning statements. These changes would also likely bring the FK score comfortably below 12.0.
While the score of 12.1 is very close to the Grade 12 target, it could benefit from minor adjustments to reach a broader audience. Here are three specific suggestions:
1. Break down compound sentences with multiple clauses: The sentence "Organizations seeking to license data can post inquiries for the Datavant ecosystem, and organizations can respond if they have data meeting the requester's criteria" contains 24 words and could be split: "Organizations seeking to license data can post inquiries for the Datavant ecosystem. Organizations can respond if they have data meeting the requester's criteria."
2. Simplify technical phrasing: Change "We do not have a way to verify responses as communications that proceed after a Data Inquiry is sent out from your own email inbox" to "We cannot verify communications that happen after you send a Data Inquiry from your email."
3. Use simpler vocabulary where possible: Replace "actionably respond" with "respond with useful information" and "designated contact" with "contact you choose."
Plain Language: Needs Attention - Some phrases are unnecessarily complex: "communications that proceed after a Data Inquiry is sent out from your own email inbox" and "if they have data meeting the requester's criteria" could be simplified.
Sentence Length: Pass - Most sentences are appropriately sized. The longest appears to be around 24-25 words, which is at the threshold but acceptable.
Jargon: Needs Attention - Several unexplained technical terms:
- "Datavant ecosystem" (not defined on first use)
- "ICD Codes" (abbreviation explained below)
- "CPT Codes" (abbreviation explained below)
- "data latency requirements" (not explained)
- "blocklist" (not explained)
Active Voice: Needs Attention - Several passive constructions found:
- "meant to be an initial outreach" → "serves as an initial outreach"
- "All responses to the inquiry will be sent" → "We will send all responses"
- "if you want to Share to the Public" could be "if you want to share publicly"
Heading Clarity: Pass - Headings are clear and action-oriented ("Create a Data Inquiry," "To View Your Data Inquiries").
Link Text: Needs Attention - "Manage Your Company Profile in Explore" appears to be link text but lacks context about what the user will learn or do.
Abbreviations: Needs Attention - "ICD Codes," "CPT Codes," and "e.g." are used without first spelling them out. Best practice is to define on first use: "International Classification of Diseases (ICD) Codes."
Overall WCAG Writing Score: Needs Attention
The content is very close to the Grade 12 target but slightly exceeds it. Here are three specific improvements:
1. Break up the compound first sentence: "The information in this article applies to general onboarding data tables. General onboarding data tables are those that are onboarded to the Datavant portal and already certified under an existing expert determination."
- Simplify to: "This article covers general onboarding data tables. These are tables onboarded to the Datavant portal that are certified under an existing expert determination."
2. Simplify the Background section opening: "For general onboarding data tables, data checks are performed when data being ingested into the Datavant Portal."
- Fix to: "We perform data checks when you ingest data into the Datavant Portal."
3. Break the lengthy compliance sentence: "Data that does not comply will cause file failures during ingestion which will need to be resolved before attempting to re-ingest again."
- Simplify to: "Non-compliant data will cause file failures. You must resolve these failures before re-ingesting the data."
Plain Language: Needs Attention - Some sentences use unnecessarily complex phrasing. Example: "onboarded to the Datavant portal and already certified under an existing expert determination" could be simplified.
Sentence Length: Pass - Most sentences are appropriately sized. Average of 17.7 words per sentence is good, though a few could be split for better clarity.
Jargon: Needs Attention - Multiple unexplained technical terms:
- "expert determination" (not defined)
- "Privacy Hub" (mentioned but not explained)
- "transform tokens" (no context provided)
- "HIPAA de-identification" (assumed knowledge)
- "Multiline Detection" (technical feature unexplained)
Active Voice: Needs Attention - Several passive constructions found:
- "data checks are performed when data being ingested"
- "Periods (.) in headers are removed"
- "Tokens are not permitted"
- "table has been certified"
Heading Clarity: Needs Attention - The article appears to lack clear hierarchical headings. "Background" and "Data Validation Rules" are present but the bulleted requirements under Background need a subheading like "Data Requirements" or "File Format Rules."
Link Text: Pass - Reference to "Privacy Hub Data Upload User Guide" is descriptive, though the actual link implementation cannot be verified from the prose text.
Abbreviations: Needs Attention - Multiple abbreviations used without first defining them:
- ICD (International Classification of Diseases)
- CPT (Current Procedural Terminology)
- HCPCS (Healthcare Common Procedure Coding System)
- DRG (Diagnosis-Related Group)
- NPI (National Provider Identifier)
- LOINC (Logical Observation Identifiers Names and Codes)
- NDC (National Drug Code)
- SNOMED CT (Systematized Nomenclature of Medicine Clinical Terms)
- CUI (Concept Unique Identifiers)
Overall WCAG Writing Score: Needs Attention
The content is slightly above the Grade 12 target (by 0.1), indicating room for improvement. Here are 3 specific suggestions:
1. Break down compound sentences with multiple clauses
- Current: "Datavant understands these tables are reviewed and analyzed by the Privacy Solutions team."
- Suggested: "The Privacy Solutions team reviews and analyzes these tables."
2. Simplify technical phrase constructions
- Current: "Segments let you reuse tables that are already onboarded to the Datavant Connect platform."
- Suggested: "Segments let you reuse tables already in the Datavant Connect platform."
3. Reduce prepositional phrase chains
- Current: "A Segment is a subset of data created from one or more parent tables."
- Suggested: "A Segment is a data subset. You create it from one or more parent tables."
Plain Language: Needs Attention - Some phrases use corporate jargon that could be simplified: "Showcasing a data asset to potential partners" could be "Showing your data to potential partners"; "derived Segments" could be "new Segments"
Sentence Length: Pass - Average sentence length is 15 words, well below the 25-word threshold
Jargon: Needs Attention - Several technical terms lack explanation on first use:
- "General Onboarding" (explained contextually but not defined)
- "Privacy Solutions project" (not defined)
- "tokens" and "tokenize" (mentioned but not explained)
- "Data Group" (title term but definition comes late in article)
Active Voice: Pass - Most content uses active voice appropriately ("You create tables", "Segments let you reuse")
Heading Clarity: Pass - Clear, descriptive headings (Tables, Segments, General Onboarding, Privacy Solutions)
Link Text: Pass - Link references are descriptive (e.g., "General Onboarding User Guide", "Understanding Assess")
Abbreviations: Pass - No unexplained abbreviations present
Overall WCAG Writing Score: Needs Attention
While the score of 12.1 is very close to the target threshold, here are three specific suggestions to bring it below Grade 12:
1. Break down compound technical sentences: The sentence "The AWS Native Tokenization is a docker container built to be deployed on either EC2, ECS, or EKS" (17 words) could be split: "The AWS Native Tokenization is a docker container. You can deploy it on EC2, ECS, or EKS."
2. Simplify the proxy server instruction: "If you have a proxy server, ensure it is configured to pass through the incoming SSL certificate from Datavant's endpoints, as opposed to passing back its own self-signed certificate" (30 words) could become: "If you have a proxy server, configure it to pass through the SSL certificate from Datavant's endpoints. Do not let it pass back its own self-signed certificate."
3. Clarify credential timing statement: "Once you generate the credential, you can't view it again" could be: "After you generate the credential, you cannot view it again. Save it immediately."
Plain Language: Needs Attention - Some phrases are unnecessarily complex: "appropriately sized," "pass-through mode," "configured to pass through the incoming SSL certificate." Consider: "correctly sized," "pass-through setting," "set to accept the SSL certificate."
Sentence Length: Flag - One sentence exceeds 25 words:
- "If you have a proxy server, ensure it is configured to pass through the incoming SSL certificate from Datavant's endpoints, as opposed to passing back its own self-signed certificate." (30 words)
Jargon: Needs Attention - Multiple technical terms lack explanation or definition:
- "docker container" (not explained for non-DevOps audiences)
- "master salt" (cryptographic term not defined)
- "pass-through mode" (not defined)
- "self-signed certificate" (not explained)
- "SSL certificate" (acronym used but not expanded on first use)
Active Voice: Pass - Most instructions use clear active voice ("Ensure your machine," "click Generate," "Do not share").
Heading Clarity: Pass - Step-based headings are clear and actionable, though "Step 2" could specify "(for tokenization only)" in the heading itself rather than in parentheses.
Link Text: Flag - Contains vague link text:
- "here" (in "You can see all of the EC2 types that AWS provides here") should be descriptive like "view AWS EC2 instance types"
- Generic references to other guides without clear link text context
Abbreviations: Needs Attention - Several abbreviations lack first-use expansion:
- OS (Operating System)
- SSL (Secure Sockets Layer)
- CLI (Command Line Interface)
- AWS is used throughout but never expanded to "Amazon Web Services"
Overall WCAG Writing Score: Needs Attention
1. Break down compound sentences with multiple clauses. For example, "When you run selected data tables through a Match job, Datavant Match uses high precision and recall to determine whether two de-identified, tokenized records in the same table, or across multiple tables, represent the same person" (33 words) could be split into: "When you run selected data tables through a Match job, Datavant Match analyzes the records. It determines whether two de-identified, tokenized records represent the same person. These records may be in the same table or across multiple tables."
2. Replace technical compound phrases with simpler alternatives. Change "Privacy-Preserving Record Linkage (PPRL)" to "secure record linking" on first reference, and "locally encrypted Datavant ID" to "encrypted Datavant ID" (removing the modifier "locally" which adds complexity without clarity for most users).
3. Simplify the data pool explanation. The sentence "Because each Match run creates its own data pool, the resulting DVIDs will differ from those in other runs and cannot be linked to DVIDs from previous or future Match runs" uses complex subordinate structure. Revise to: "Each Match run creates its own data pool. The DVIDs from one run will differ from other runs. You cannot link DVIDs across different Match runs."
Plain Language: Needs Attention - Several instances of complex technical phrasing: "Privacy-Preserving Record Linkage (PPRL)," "high precision and recall," "de-identified, tokenized records," "referential data," and "configurable matching thresholds" appear without adequate plain-language explanation.
Sentence Length: Mostly Pass - Most sentences are under 25 words. One flagged exception: "When you run selected data tables through a Match job, Datavant Match uses high precision and recall to determine whether two de-identified, tokenized records in the same table, or across multiple tables, represent the same person" (43 words).
Jargon: Needs Attention - Multiple unexplained terms: "precision and recall" (data science metrics), "de-identified," "tokenized," "referential data," "data pool," "matching thresholds," "data standardization and quality protocols," and "enterprise-wide identification resolution."
Active Voice: Pass - Article predominantly uses active voice ("Datavant Match provides," "Match assigns," "Datavant distributes"). No significant passive constructions detected.
Heading Clarity: Pass - Headings are clear and descriptive: "What is Match?", "Key benefits", "Perform a Match job", "Referential Data". They effectively preview content.
Link Text: Pass - Link text is descriptive: "Understanding Distributions" and "How to Run Match" clearly indicate destination content.
Abbreviations: Needs Attention - PPRL is explained on first use (good), DVID is explained on first use (good), but PII appears in "Even when underlying PII changes" without prior definition or expansion.
Overall WCAG Writing Score: Needs Attention
The content meets the Grade 12 target threshold, but here are three specific suggestions to improve readability further:
1. Break down complex compound sentences: The sentence "Data uploaded to the platform must either: Have an expert determination certifying it as de-identified Adhere to Datavant's pre-certified Profile Model, or Not be covered by HIPAA" combines multiple conditions in a way that increases cognitive load. Split this into separate, clearly numbered requirements (1. Have an expert determination... 2. Adhere to Datavant's... 3. Not be covered by HIPAA).
2. Simplify technical explanations: The definition "Flattened Parquet files remove nested structures and arrays by transforming data into a single-level format" uses abstract technical language. Rewrite as: "Flattened Parquet files convert complex, multi-layered data into a simple, single-level table format."
3. Reduce multi-clause sentences: The sentence "Nested fields are flattened into dot-delimited keys (e.g., Address.Street), while arrays are either combined into a single string (e.g.,"Lupus, Rheumatoid Arthritis, Psoriasis") or expanded into multiple rows" contains 28 words with multiple subordinate clauses. Break into two sentences: "Nested fields become dot-delimited keys (e.g., Address.Street). Arrays are either combined into a single string or expanded into multiple rows."
Plain Language: Needs Attention - Terms like "deidentified, tokenized data table," "overlap stack," "flat and delimited," and "dot-delimited keys" appear without initial explanation. The phrase "datavant-[your_site] transit encryption key" assumes substantial prior knowledge.
Sentence Length: Needs Attention - One sentence exceeds 25 words: "Nested fields are flattened into dot-delimited keys (e.g., Address.Street), while arrays are either combined into a single string (e.g.,"Lupus, Rheumatoid Arthritis, Psoriasis") or expanded into multiple rows" (28 words).
Jargon: Needs Attention - Unexplained technical terms include: "tokenized," "deidentified," "overlap stack," "profile reporting," "flat and delimited," "nested data," "dot-delimited keys," "transit encryption key," "CLI," "millisecond/second timestamps," and "microsecond and nanosecond timestamps."
Active Voice: Pass - The article primarily uses active voice constructions. Minor passive uses are appropriate in context (e.g., "Data must be certified").
Heading Clarity: Pass - Headings are descriptive and informative ("Onboarding Requirements," "Important Considerations on Parquet Files," "File Size Limitations").
Link Text: Needs Attention - The phrase "access it here" is vague link text. Should specify destination like "access the onboarding demo video."
Abbreviations: Needs Attention - "HIPAA," "CLI," ".csv," ".parquet," ".xml," ".pdf" appear without first spelling out the full term. "CLI" particularly needs explanation as "Command Line Interface."
Overall WCAG Writing Score: Needs Attention
✓ Content meets the Grade 12 target threshold. Well done! The article successfully balances technical accuracy with readability, maintaining an average of 15.6 words per sentence and 1.82 syllables per word. This is appropriate for a technical healthcare security topic. To maintain or improve this score, continue using clear examples (like "John Smith, Male, 03/27/1968") and breaking complex processes into numbered steps.
Plain Language: Needs Attention
- "Tokens are encrypted" - sentence appears incomplete at the end
- "Master Token is encrypted with a site-specific key to generate the final encrypted patient token" contains nested technical concepts that could be simplified
- Consider: "The Master Token is then encrypted using a unique key for each site. This creates the final patient token."
Sentence Length: Pass
- Longest sentence is 24 words ("Identical patient information always produces the same Master Token, but site-specific encryption ensures each site creates a unique token, or a site-specific token, for the same patient")
- Most sentences are well under 25 words
Jargon: Needs Attention
- "PII" - abbreviated on first use without definition
- "soundex" - unexplained technical term
- "SHA-256 irreversible hash function" - technical term without plain language explanation
- "de-identified" - used before clear definition
- "Master Token" - concept introduced but could use simpler explanation
Active Voice: Pass
- Good use of active voice throughout ("Tokens allow organizations to link," "Tokens are generated in three steps")
- Passive constructions used appropriately for technical processes
Heading Clarity: Pass
- Clear hierarchical structure with descriptive headings
- "What are Datavant tokens?" directly answers user questions
- Process steps clearly numbered and labeled
Link Text: Good
- "Token Error Log File" is descriptive
- "Required Data Pre-Processing" is specific and clear
- No vague "click here" or "read more" links found
Abbreviations: Needs Attention
- "PII" - used extensively but never defined in the provided text
- "CLI" - defined contextually as "Datavant CLI v5" but acronym not spelled out
- "v4" and "v5" - version abbreviations are acceptable
Overall WCAG Writing Score: Needs Attention
Primary issues: Define PII on first use, explain technical terms like "soundex" and "SHA-256 hash function" in plain language, and complete the final incomplete sentence about token encryption.
The content nearly meets the target readability level. Here are three specific suggestions to improve it further:
1. Break down dense compound sentences: The sentence "This secret key is provided as an input to ensure that the Aggregated Overlap is (a) anonymous under the GDPR and (b) unique to the two partners involved" (29 words) could be split: "This secret key is provided as an input. It ensures that the Aggregated Overlap is anonymous under GDPR. It also makes the overlap unique to the two partners involved."
2. Simplify multi-clause explanations: The sentence "Each site will locally create an Overlap Filter, an anonymous, population-level data structure based on their tokenised dataset" contains technical layering. Revise to: "Each site will locally create an Overlap Filter. This is an anonymous data structure. It works at the population level and uses your tokenised dataset."
3. Replace complex terminology with simpler alternatives where possible: "Partners must choose the larger of the two sizes and provide this as an input to the Datavant application, to ensure that the Overlap Filters are compatible between partners" could become: "Partners must choose the larger dataset size. Provide this size to the Datavant application. This ensures both Overlap Filters work together."
Plain Language: Needs Attention - Terms like "tokenised dataset," "population-level data structure," and "Overlap Filter" appear without initial explanation. Consider adding brief definitions on first use.
Sentence Length: Needs Attention - One sentence exceeds 25 words: "This secret key is provided as an input to ensure that the Aggregated Overlap is (a) anonymous under the GDPR and (b) unique to the two partners involved" (29 words). Consider breaking this into shorter sentences.
Jargon: Needs Attention - Unexplained technical terms include: "Overlap Filter," "tokenised dataset," "population-level data structure," "Datavant Connect Key," "SFTP," and "CLI." While some are product-specific, brief explanations would improve accessibility.
Active Voice: Pass - Most sentences use active voice effectively (e.g., "Each site will locally create," "Work with your Customer Experience representative").
Heading Clarity: Good - Step-by-step headings are clear and action-oriented (e.g., "Step 1. Ensure you have a Datavant Connect Key").
Link Text: Pass - No link text present in the cleaned prose to evaluate.
Abbreviations: Needs Attention - "GDPR," "SFTP," and "CLI" appear without expansion on first use. Always spell out abbreviations initially: "General Data Protection Regulation (GDPR)," "Secure File Transfer Protocol (SFTP)," "Command Line Interface (CLI)."
Overall WCAG Writing Score: Needs Attention
1. Break down long compound sentences: The sentence "You can complete steps 1–3 in this article for service accounts, as long as the account has an associated email address (or alias)" could be split into two simpler sentences: "You can complete steps 1–3 in this article for service accounts. The account must have an associated email address (or alias)."
2. Simplify technical explanations: The phrase "Datavant recommends maintaining two active credentials to allow rotation without downtime when one expires" uses the technical term "rotation" without explanation. Revise to: "Datavant recommends keeping two active credentials. This way, you can switch between them without service interruption when one expires."
3. Reduce syllable-heavy words where possible: Replace "generate" with "create" throughout (appears 4 times), "retrieve" with "get," and "nears expiration" with "is about to expire." These simpler alternatives maintain meaning while improving readability.
Plain Language: Needs Attention - Terms like "rotation without downtime," "user-specific credential," and "UAT pipelines" could be explained more clearly. The phrase "allow rotation without downtime" assumes technical knowledge.
Sentence Length: Flag - One sentence exceeds 25 words: "Datavant recommends maintaining two active credentials to allow rotation without downtime when one expires.It is also recommended to create two portal accounts for the production pipeline." (28 words, also contains a punctuation error with missing space after period)
Jargon: Needs Attention - Several unexplained technical terms:
- "UAT pipelines" (UAT is explained in Abbreviations, but "pipeline" is not defined)
- "status code 1" (no explanation of what this means)
- "runtime" (could use "when running")
- "rotation" (in credential context)
Active Voice: Pass - Most sentences use active voice appropriately. One minor passive construction: "The credentials provided are invalid" in the error message, but this is acceptable for error messages.
Heading Clarity: Pass - Headings are clear and action-oriented (Step 1, Step 2, Step 3 with descriptive labels)
Link Text: Pass - Link references are descriptive: "Managing Users For Your Company," "Generate Datavant Credentials," "Datavant CLI Commands and Optional Arguments"
Abbreviations: Flag - "UAT" appears without explanation. "CLI" appears in title but is not expanded on first use in body text (though it may be defined in parent documentation).
Overall WCAG Writing Score: Needs Attention
1. Break down long compound sentences: The sentence "Configurations can be used in the following manner: Tokenization: Use this when only looking to tokenize and de-identify data Data Onboarding: Use this when only looking to onboard tokenized and de-identified data to the Datavant Connect platform Tokenization and Data Onboarding: Use this when you need to tokenize and de-identify data and onboard data to the Datavant Connect platform" runs together as a single complex structure. Split this into a bulleted list with separate, complete sentences for each use case.
2. Simplify technical phrases: Replace complex constructions like "a mapping of rules to fields contained within a data table" with simpler alternatives such as "a set of rules that define how data fields are processed." Similarly, "enumerating column numbers along with each column's content" could become "listing each column number and what it contains."
3. Reduce nested explanations: The sentence "Select if you want to activate configuration auto-detection. This will help auto-create tokens when you create a configuration for the first time [optional]" embeds explanation within instruction. Simplify to: "You can activate configuration auto-detection. This feature auto-creates tokens for new configurations."
Plain Language: Needs Attention - Several complex phrases present barriers: "mapping of rules to fields contained within a data table," "enumerating column numbers along with each column's content," and "the mapped column positions must match the input file" use technical construction that could be simplified.
Sentence Length: Flag - The opening definition sentence contains 93 words when formatted as prose: "A configuration is a mapping of rules to fields contained within a data table and is used for tokenization and data onboarding to the Datavant Connect Platform...Tokenization and Data Onboarding: Use this when you need to tokenize and de-identify data and onboard data to the Datavant Connect platform." This far exceeds the 25-word recommendation.
Jargon: Needs Attention - Multiple unexplained technical terms: "tokenization," "de-identify," "data onboarding," "PII" (later used without definition), "tokenization engine," "mapped column positions." While some are defined elsewhere, they should be briefly explained on first use within this article.
Active Voice: Pass - Most instructions use active voice effectively ("select Add Configuration," "Review the input column names," "Populate the text box").
Heading Clarity: Pass - Step-by-step headings are clear and sequential (Step 1, Step 2, etc.), making navigation predictable.
Link Text: Needs Attention - "access it here" and "refer to the What is a Configuration user guide" are functional but could be more descriptive. "here" should be avoided; use "watch the configuration demo video" instead.
Abbreviations: Flag - "PII" appears without being spelled out as "Personally Identifiable Information" on first use.
Overall WCAG Writing Score: Needs Attention
The content meets the target of Grade 12 or below, sitting at 11.8. However, here are three specific suggestions to improve readability further:
1. Break down multi-clause sentences: The opening sentence contains 34 words with multiple clauses: "If you have data you are expecting from a partner, a Token Export, Match Run, or Privacy Hub Remediated tables, this guide will walk you through how to retrieve data that has been delivered via the Distribution tool." Split this into two sentences: "This guide explains how to retrieve data delivered via the Distribution tool. Use this process for data from partners, Token Exports, Match Runs, or Privacy Hub Remediated tables."
2. Simplify technical phrase structures: The phrase "an AWS IAM role that your organization can 'assume' through your organization's AWS IAM user" is dense. Rewrite as: "an AWS IAM role. Your organization assumes this role through your AWS IAM user."
3. Reduce nested instructions: The credential retrieval steps combine navigation with action in long sequences. Instead of "If you do not see this SFTP Credentials section or are running into an error when attempting to generate credentials, reach out to your company's Admin to have them update your user permissions," use: "Can't see the SFTP Credentials section? Contact your Admin. They can update your user permissions."
Plain Language: Needs Attention - Some phrases are unnecessarily complex. Examples: "Datavant-provisioned AWS IAM role" could add brief explanation; "assume the role" uses technical jargon that may confuse non-AWS users; "bro" appears cut off at the end suggesting incomplete content.
Sentence Length: Flagged - One sentence exceeds 25 words:
- Opening sentence (34 words): "If you have data you are expecting from a partner, a Token Export, Match Run, or Privacy Hub Remediated tables, this guide will walk you through how to retrieve data that has been delivered via the Distribution tool."
Jargon: Needs Attention - Several technical terms lack explanation:
- "SFTP" (explained later but not on first use)
- "AWS IAM role" (no explanation of what "assume" means in this context)
- "S3 bucket"
- "Switchboard SFTP" (relationship to regular SFTP unclear)
- "site-specific encryption key"
Active Voice: Pass - Article primarily uses active voice ("Click Get Switchboard SFTP Credentials," "Navigate to your site's /outbound folder")
Heading Clarity: Pass - Headings are clear and action-oriented ("Determine How to Pick Up Distributed Data," "Connect to the Datavant SFTP / S3," "Pick up Files")
Link Text: Needs Attention - Reference to "Data Onboarding Method: S3 Transfer" appears as standalone text rather than descriptive link context. Should read: "review how to generate an S3 IAM Role in the Data Onboarding Method guide" if it's a link.
Abbreviations: Needs Attention - Multiple unexplained abbreviations:
- SFTP (later explained as context, but not defined)
- AWS (not defined)
- IAM (not defined)
- CLI (not defined)
- API (not defined)
- S3 (not defined)
Overall WCAG Writing Score: Needs Attention
1. Break down compound sentences with multiple clauses. For example, "This article is for customers setting up Datavant's native tokenization solution on AWS Elastic Container Service (ECS).The product lets your organization tokenize data, transform tokens, and onboard directly to the Datavant Connect platform - all within your own AWS account." could be split into shorter, clearer statements: "This article is for customers setting up Datavant on AWS ECS. The product runs in your own AWS account. It lets you tokenize data, transform tokens, and onboard to Datavant Connect."
2. Replace multi-syllable words with simpler alternatives where possible. Terms like "prerequisites" (4 syllables) could become "requirements" (3 syllables), "organizations" (5 syllables) could become "companies" (3 syllables), and "authorization" could become "approval" or "access."
3. Simplify technical explanations by removing redundant phrases. For example, "The solution lets you tokenize, transform, and onboard datasets within your own AWS environment. It uses a secure, scalable, container-based approach that keeps your data under your control" could be: "The solution lets you tokenize, transform, and onboard datasets in your AWS environment. Your data stays under your control."
Plain Language: Needs Attention - Several instances of unnecessary complexity: "packaged as a Docker container and integrates with key AWS services" could be "packaged as a Docker container and works with key AWS services"; "ensure that you have the necessary permissions" could be "make sure you have the right permissions."
Sentence Length: Pass - The average sentence length of 14.5 words is well within acceptable limits. No sentences appear to exceed 25 words in the provided text.
Jargon: Needs Attention - Several unexplained technical terms: "tokenization," "ETL," "ECS Fargate task," "Docker container." While some AWS service names are explained (like ECS being Elastic Container Service), core concepts like "tokenization" should have a brief explanation at first use.
Active Voice: Needs Attention - Multiple passive constructions found: "is packaged as a Docker container," "is designed for organizations," "is stored," "is only required." Suggested rewrites: "We package the image as a Docker container," "We designed this deployment for organizations," "where you store your S3 data," "You only need this step."
Heading Clarity: Pass - Headings are clear, action-oriented, and follow a logical sequence (Step 1, Step 2, etc.). "Prerequisites" clearly indicates what's needed before starting.
Link Text: Good - No vague link text detected in the prose. References like "Understanding Configurations" are descriptive and contextual.
Abbreviations: Needs Attention - "IAM," "ECS," "ETL," "CLI," and "S3" are used without first defining them. While "AWS Identity and Access Management (IAM)" and "AWS Elastic Container Service (ECS)" are properly introduced, "ETL" (Extract, Transform, Load) and "CLI" (Command Line Interface) lack definitions.
Overall WCAG Writing Score: Needs Attention
The content meets the readability target of Grade 12 or below. Here are three specific suggestions to improve it further:
1. Break up compound sentences with multiple clauses. For example, "User-specific logging of application access. Easy credential management, refreshing or revoking quickly for departing employees or compromised accounts" uses sentence fragments. Combine these into complete, simpler sentences: "The system logs each user's access. You can quickly refresh or revoke credentials for departing employees or compromised accounts."
2. Simplify technical phrasing. The phrase "Additional data validations and pre-processing steps have been introduced for several PII fields" could be rewritten as: "We added new data checks and pre-processing for several PII fields."
3. Reduce multi-syllable words where possible. Replace "executable" (4 syllables) with "program file" or "application," "authentication" (5 syllables) with "login" or "sign-in," and "credentials" (3 syllables) with "login details" where context allows.
Plain Language: Needs Attention - Phrases like "ensure compliance," "pre-processing steps," and "diagnose subcommand" use technical jargon without definition. "Introduces major improvements" could be simplified to "adds important updates."
Sentence Length: Pass - Most sentences are concise. The breakdown shows average sentence length of 11.6 words, well below the 25-word threshold.
Jargon: Needs Attention - Several unexplained technical terms:
- DeId (tokenization)
- Link (transformation)
- FHIR data standard
- Series 100 tokens
- SFTP
- Subcommand (used multiple times)
- PII fields
Abbreviations: Needs Attention - Multiple unexplained abbreviations:
- CLI (only appears in title, never spelled out)
- HITRUST
- ISO
- FedRAMP
- FHIR
- PII
- UI
- SFTP
Active Voice: Mostly Pass - One passive construction flagged: "Additional data validations and pre-processing steps have been introduced" should be "We introduced additional data validations and pre-processing steps."
Heading Clarity: Pass - "Key Changes" clearly signals the main content section, though subheadings for each feature (One executable, User-level authentication) are descriptive and helpful.
Link Text: Pass - Link references are descriptive: "Upgrade to Datavant v4," "Network Errors and Diagnostic Mode," and "v4.1.0 Release Notes" all clearly indicate destination content.
Overall WCAG Writing Score: Needs Attention
1. Break up the opening sentence: The first sentence contains 16 words and multiple technical concepts. Consider splitting it: "Datavant can be deployed through native applications on three major cloud platforms. These platforms include AWS, Snowflake, and Databricks." This separates the main concept from the specific examples.
2. Simplify multi-syllable technical phrases: Replace "functionally align with" (6 syllables) with simpler alternatives like "work like" or "match" to reduce syllable density. The phrase "CLI-specific execution modes" could become "special CLI modes" to improve accessibility.
3. Shorten the compound sentence about fees and availability: The sentence "Additional fees may apply for cloud deployments. The CLI and Desktop versions are available for immediate use." works well separately, but consider making the fee information more direct: "Cloud deployments may have extra costs. CLI and Desktop versions are ready to use now."
Plain Language: Needs Attention - Phrases like "functionally align with," "token-transformation workflows," and "CLI-specific execution modes" use technical jargon that could be simplified for broader accessibility.
Sentence Length: Pass - The longest sentence is 24 words ("These platforms functionally align with Datavant CLI for core tokenization and token-transformation workflows, but not for CLI-specific execution modes like server or streaming mode"), which is just under the 25-word threshold.
Jargon: Needs Attention - Several technical terms lack explanation: "tokenization," "token-transformation workflows," "CLI," "streaming mode," "server mode," "EC2," "ECS," "EKS." While "CLI" and cloud platform names may be familiar to the technical audience, first-use definitions would improve accessibility.
Active Voice: Pass - Most sentences use active voice effectively. The only passive construction "are available" is acceptable and clear.
Heading Clarity: Needs Attention - The article appears to list platform names (AWS, Databricks, Snowflake) as headings without clear descriptive text. These should be formatted as proper headings with context, such as "AWS Deployment Options" or "Available AWS Implementation Guides."
Link Text: Needs Attention - Link text like "Use Datavant Natively on AWS EC2" is descriptive, but the presentation suggests these may appear as bare links without surrounding context. Ensure links are embedded in descriptive sentences.
Abbreviations: Needs Attention - Multiple unexplained abbreviations: CLI (Command Line Interface), AWS (Amazon Web Services), EC2 (Elastic Compute Cloud), ECS (Elastic Container Service), EKS (Elastic Kubernetes Service). These should be spelled out on first use.
Overall WCAG Writing Score: Needs Attention
The content successfully meets the Grade 12 target. Here are three specific suggestions to improve readability further:
1. Break up compound sentences with multiple clauses. For example, "Datavant regularly provides application updates that may include new features, enhancements, bug fixes, security patches, or documentation improvements" could become two sentences: "Datavant regularly provides application updates. These may include new features, enhancements, bug fixes, security patches, or documentation improvements."
2. Simplify technical explanations. The semantic versioning section uses parenthetical examples that add complexity. Instead of "X (major version). An increase (for example, v4.0.0 → v5.0.0) means significant changes that are not backward compatible," try: "X is the major version number. When it increases (like v4.0.0 to v5.0.0), the changes are not backward compatible."
3. Replace multi-syllable words where possible. Change "deployments" to "versions," "deprecated" to "retired," and "underlying dependencies" to "required software" to reduce syllable count and improve clarity.
Plain Language: Needs Attention - Several phrases use unnecessary complexity: "continuous innovation," "application deployments may be retired," "backward-compatible," and "underlying dependencies" could be simplified.
Sentence Length: Pass - Most sentences stay under 25 words. The longest appears to be around 23 words, which is acceptable.
Jargon: Needs Attention - Several technical terms lack explanation for general audiences:
- "semantic versioning" (linked but not defined)
- "backward compatible" (used multiple times, never explained)
- "language runtimes" (not defined)
- "dependencies" (used throughout but only examples given, not definition)
- "deprecated" (no explanation)
Active Voice: Needs Attention - Several passive constructions found:
- "may be retired and replaced"
- "is managed by either its language community"
- "are listed below"
- "may be removed"
Heading Clarity: Pass - Headings are descriptive and clear (Overview, Versioning, Dependency Lifecycle, Support Period, Availability).
Link Text: Pass - The link "Semantic Versioning 2.0.0" is descriptive and tells users where they're going.
Abbreviations: Needs Attention
- "CLI" - not explained
- "AWS" - not explained (Amazon Web Services)
- "OS" - explained after first use, which is good
- "X.Y.Z" - explained contextually
Overall WCAG Writing Score: Needs Attention
The content meets the Grade 12 target but sits close to the threshold. Here are three specific suggestions to improve readability further:
1. Break down long compound sentences: The sentence "Customers often use Profile reports to double-check data they have recently onboarded, get high-level counts of patients on their table to respond to a potential partner's feasibility request, and quickly compare multiple tables across a single criteria, such as prevalence of a certain diagnosis code" contains 47 words with multiple clauses. Split this into 2-3 shorter sentences focusing on one use case at a time.
2. Simplify technical phrases: Replace multi-syllable phrases like "computed on the token matching criteria" with simpler alternatives such as "calculated using the token settings" and change "Total number of individuals in a given data table" to "Total individuals in the data table."
3. Reduce nested prepositional phrases: The phrase "click on the table's name on the left navigation bar of the report" stacks three prepositional phrases. Simplify to "In the left navigation bar, click the table name" to reduce cognitive load.
Plain Language: Needs Attention - Several complex phrases could be simplified: "metadata report on a data table" could be "data summary report"; "feasibility request" needs context; "computed on Tokens 1 and 2" uses technical jargon without explanation.
Sentence Length: Needs Attention - One sentence exceeds 25 words significantly: "Customers often use Profile reports to double-check data they have recently onboarded, get high-level counts of patients on their table to respond to a potential partner's feasibility request, and quickly compare multiple tables across a single criteria, such as prevalence of a certain diagnosis code." (47 words)
Jargon: Needs Attention - Multiple technical terms lack explanation or context: "metadata report," "onboarded," "feasibility request," "Tokens 1 and 2," "token matching criteria," "Billing Physician NPI," "Onboarding Checks." First use should include brief definitions.
Active Voice: Pass - Most sentences use active voice effectively ("click Create Report," "Select the filters," "The filter will apply").
Heading Clarity: Good - Step-based headings are clear and action-oriented. The numbered steps with action verbs help users navigate the process.
Link Text: Pass - No vague "click here" links detected. References like "My Data Management page" are descriptive.
Abbreviations: Needs Attention - "NPI" is not defined on first use (National Provider Identifier). While common in healthcare contexts, it should be spelled out initially.
Overall WCAG Writing Score: Needs Attention
The content meets the target grade level of 12 or below, which is appropriate for technical documentation. However, here are three specific ways to improve readability further:
1. Simplify compound technical phrases: Phrases like "tokenizing and de-identifying data, and when onboarding data to the Datavant Connect platform" contain multiple clauses and technical actions. Break these into separate, simpler statements such as "Use this to tokenize data. It also de-identifies data. You can onboard data to the platform."
2. Reduce prepositional phrase chains: The sentence "For more information on other deployment options for the Datavant tokenization software, see The Datavant Tokenization Software" stacks multiple "of/on/for" phrases. Simplify to: "To learn about other deployment options, see The Datavant Tokenization Software."
3. Break down multi-step instructions within sentences: "Go to the Datavant Application Credential section, and select Generate" combines navigation and action. Split into: "Go to the Datavant Application Credential section. Select Generate."
Plain Language: Needs Attention - Some phrases use unnecessarily formal constructions. "This article includes information that relates to" could be simplified to "This article covers." The phrase "which is available on limited release" could be "currently in limited release."
Sentence Length: Pass - The average sentence length is 14 words, well below the 25-word threshold. Most sentences are concise and appropriate for technical documentation.
Jargon: Needs Attention - Several technical terms lack explanation:
- "stdin" and "stdout" (standard input/output) - unexplained abbreviations
- "on-premise" - used without clarification
- "tokenization" and "de-identifying" - core concepts assumed as known
- "CLI" - defined once but heavily used throughout
Active Voice: Pass - Most instructions use active voice effectively ("Go to," "Click," "Select," "Download"). No problematic passive constructions identified.
Heading Clarity: Pass - Headings follow a clear step-by-step structure (Step 1, Step 2, etc.) and use descriptive action-oriented language that tells users what they'll accomplish.
Link Text: Needs Attention - Contains vague link text: "Download link" appears multiple times without context of what is being downloaded. "Download File" could specify "Download credentials.txt file."
Abbreviations: Needs Attention -
- "CLI" is defined on first use but "v5" is not explained
- "stdin" and "stdout" appear without definition
- Email address format "support@datavant.com" is standard and acceptable
Overall WCAG Writing Score: Needs Attention
The content meets the Grade 12 target threshold, but these specific improvements will enhance readability:
1. Simplify complex noun phrases: Replace technical constructions like "site-specific token encryption" and "Irreversible hashing" with shorter, more direct alternatives. For example, "Site-specific token encryption" could become "How sites encrypt tokens" as a heading, making it more action-oriented and clearer.
2. Break down the dense definitional sentence: The sentence "A site is a token encryption key" followed immediately by technical explanation creates cognitive load. Restructure this section to separate the definition from the explanation: "What is a site? A site is a token encryption key. You can use it to encrypt tokens in a unique way for your organization."
3. Expand abbreviations on first use: "PII (Personally Identifiable Information)" appears early but the abbreviation is used heavily throughout. Consider using the full term more frequently or providing a brief reminder when PII reappears after several paragraphs to reduce memory burden on readers.
Plain Language: Needs Attention - Several technical phrases lack context: "token transformation," "Master Token," "linkability of its data," and "connect key or transit key" are introduced without sufficient explanation for non-expert readers.
Sentence Length: Pass - Most sentences are appropriately short. The longest sentence is 24 words ("Token transformation is required whenever tokens are exchanged with a partner for linking"), which is within acceptable limits.
Jargon: Needs Attention - Multiple unexplained technical terms: "linkability," "de-identification," "transit keys," "connect keys," "token transformation," and "Master Token" (while mentioned, not fully explained in accessible terms).
Active Voice: Needs Attention - Several passive constructions found: "encryption keys are provisioned," "these are unique," "site keys are available," "Token transformation is required," "Tokens are irreversible." Consider: "Datavant provisions encryption keys," "We make these unique," "You can find site keys," "You must transform tokens," "We cannot reverse tokens."
Heading Clarity: Needs Attention - "Transforming Token Encryption Keys" is noun-heavy. Consider "How to Transform Token Encryption Keys" or "When You Need to Transform Tokens." The heading "Why it matters" is clear and effective.
Link Text: Cannot Assess - No link text visible in the cleaned prose (references to other articles present but actual link text not shown in format provided).
Abbreviations: Pass with Minor Note - PII is expanded on first use. However, consider expanding it again when it reappears later in the document.
Overall WCAG Writing Score: Needs Attention
The content meets the target of Grade 12 or below, but here are three specific suggestions to improve readability further:
1. Break down complex conditional sentences: The sentence "Where multiple variables must be used in combination to link between two tables, the variables should be listed in separate rows of the schema [Rows 2 and 3, link (a)], these will be treated as an 'AND' condition, where both variables have to match across the tables for the link to be established" is 54 words long with multiple clauses. Split this into 2-3 shorter sentences focusing on one concept each.
2. Simplify compound instructions: The sentence "For instance, in the example shown, the Patient table links to the Claims table which in-turn links to the Procedures table" uses nested relationships. Restructure to: "In the example shown, the Patient table links to the Claims table. The Claims table then links to the Procedures table."
3. Use simpler vocabulary alternatives: Replace "redundant links" with "duplicate links" and "explicit linking path" with "direct link" to reduce syllable count and improve clarity without losing technical accuracy.
Plain Language: Needs Attention - Phrases like "provide an accurate assessment of the risk contained in your dataset" and "working outwards, to avoid redundant links" could be simplified. Consider: "understand the risk in your dataset" and "avoid duplicate links."
Sentence Length: Flagged - Three sentences exceed 25 words:
- "Where multiple variables must be used in combination to link between two tables, the variables should be listed in separate rows of the schema [Rows 2 and 3, link (a)], these will be treated as an 'AND' condition, where both variables have to match across the tables for the link to be established." (54 words)
- "As a guide, we recommend beginning from the patient-level table (if it exists) and working outwards, to avoid redundant links." (20 words - borderline but acceptable)
- "Where two (or more) variables can be used separately to link tables, the most specific variable should be used, for instance, in the example shown, the Patient table should link to the Claims table via the claim_id, since a single patient can have multiple claims." (47 words)
Jargon: Needs Attention - Technical terms used without explanation:
- "dataset" (first use should be defined)
- "patient-level table"
- "variable(s)" (used throughout but never defined)
- "schema" (defined by context but not explicitly)
Active Voice: Mostly Pass - One passive construction flagged: "instructions are provided with worked example visuals below" - could be: "this article provides instructions with worked example visuals below."
Heading Clarity: Pass - The heading "Create a Linking Schema Document" clearly describes the content that follows.
Link Text: Pass - "Download Linking Schema Template" is descriptive and action-oriented.
Abbreviations: Pass - No unexplained abbreviations found.
Overall WCAG Writing Score: Needs Attention
The content is close to the Grade 12 target, requiring only modest improvements:
1. Break down compound sentences with multiple clauses. For example: "When first landing on the main My Data page, you will be able to see all tables loaded to the Datavant Connect Platform by your organization" could be simplified to two sentences: "When you first land on the main My Data page, you'll see all your tables. These are tables loaded to the Datavant Connect Platform by your organization."
2. Simplify conditional and parenthetical phrases. The phrase "If you are looking to onboard data for a Privacy Hub project, refer to the Privacy Hub Data Upload Guide if you need to tokenize your data, or the Streamlined Privacy Hub Onboarding Flow if you only need to onboard data (ie. tokenization is not required)" contains nested conditions. Break this into bullet points or separate sentences for each scenario.
3. Replace formal constructions with simpler alternatives. Change phrases like "This includes all General Onboarding and Privacy Hub tables of all loaded statuses" to "This includes all General Onboarding and Privacy Hub tables with any loaded status" and "where each table page includes four available tabs that offer various data table management" to "where each table page has four tabs for managing your data."
Plain Language: Needs Attention - Several bureaucratic phrases found: "Created tables are then made available in the table list," "offer various data table management," and "modify the criteria for segment creation and return to the Segment Builder flow" could be more conversational.
Sentence Length: Needs Attention - Several sentences exceed 25 words:
- "When first landing on the main My Data page, you will be able to see all tables loaded to the Datavant Connect Platform by your organization." (27 words)
- "This includes all General Onboarding and Privacy Hub tables of all loaded statuses (Success, Failed, Not Loaded, In Progress)." (19 words but dense with technical terms)
- "If you are looking to onboard data for a Privacy Hub project, refer to the Privacy Hub Data Upload Guide if you need to tokenize your data, or the Streamlined Privacy Hub Onboarding Flow if you only need to onboard data (ie. tokenization is not required)." (48 words)
Jargon: Needs Attention - Technical terms used without explanation: "tokenize/tokenization," "Segments," "Data Groups," "General Onboarding," "Privacy Hub," and "On Demand" status. While some link to definitions, inline context would help.
Active Voice: Pass - Mostly active voice with good use of "you can" constructions. Minor passive instance: "Created tables are then made available" could be "You can then access created tables."
Heading Clarity: Pass - The article mentions clear section tabs (My Data, Shares, Activity) and uses descriptive subheadings like "Segment Details and Permissions."
Link Text: Pass - Link text appears descriptive (e.g., "What is a Table, Segment, and Data Group?", "Managing Tables", "General Onboarding User Guide").
Abbreviations: Needs Attention - "ie." should be spelled out as "that is" or "i.e." with proper formatting and explanation.
Overall WCAG Writing Score: Needs Attention
The content nearly meets the Grade 12 target. Here are 3 specific suggestions to improve readability further:
1. Break down compound sentences with multiple clauses. For example, "If you are running an Overlap report on tables that have been onboarded to the Datavant platform directly, you may select up to 10 tables" could become two shorter sentences: "You can run Overlap reports on tables onboarded directly to Datavant. These reports support up to 10 tables."
2. Simplify technical phrases. Replace "tables that have been registered via AWS" with "tables registered through AWS" and change "gauge the feasibility of data partnerships" to the simpler "check if data partnerships will work."
3. Convert long instructional sentences into bulleted lists. The sentence "You can run Assess tools on available tables, including tables you own, tables shared with your organization, and On Demand tables" would be clearer as a bulleted list of the three table types.
Plain Language: Needs Attention - Phrases like "gauge the feasibility," "patient cohort overall," and "onboarded to the Datavant platform" use business jargon that could be simplified.
Sentence Length: Pass - Average of 20.6 words per sentence is well within acceptable limits, though a few sentences approach the 25-word threshold.
Jargon: Needs Attention - Several unexplained technical terms: "Tokens 1 and 2," "token criteria," "fill rates for tokens," "subscription tier," "patient cohort," and "On Demand tables" need definitions or context on first use.
Active Voice: Pass - The article primarily uses active voice with clear imperative instructions ("Select up to 10 tables," "Click Select Filters").
Heading Clarity: Good - Step-by-step headings are clear and descriptive, though "Step 3 (Optional). Select Filters" could be more descriptive as "Step 3 (Optional). Apply Filters to Your Patient Data."
Link Text: Cannot assess - The cleaned prose text does not contain actual hyperlink text to evaluate.
Abbreviations: Needs Attention - "AWS" appears without being spelled out on first use as "Amazon Web Services."
Overall WCAG Writing Score: Needs Attention
The content nearly meets the Grade 12 target. Here are three specific suggestions to improve readability further:
1. Break up long, multi-clause sentences: The sentence "To the extent the tokens are intended to be part of a de-identified dataset, these IDs could create the capability to re-identify or link to additional data outside of intended use" (30 words) is dense and contains multiple abstract concepts. Simplify to: "If tokens are part of a de-identified dataset, these IDs create risk. They could allow someone to re-identify patients or link to unintended data."
2. Simplify complex noun phrases: Replace "the capability to re-identify" with "the ability to re-identify." Change "As part of our mission to connect the world's health data in a privacy-preserving way" to "To connect the world's health data while preserving privacy."
3. Use shorter alternatives for wordy phrases: Change "In some circumstances, passthrough IDs may be necessary in order to join tables" to "Sometimes, passthrough IDs are needed to join tables." Replace "you can refer to the process as follows" with "follow these steps."
Plain Language: Needs Attention - Several unnecessarily complex phrases: "As part of our mission to connect the world's health data in a privacy-preserving way," "tightening controls on when tokens (and associated data) can be mapped," "the capability to re-identify," and "what your expert determination allows you to do."
Sentence Length: Flag - One sentence exceeds 25 words: "To the extent the tokens are intended to be part of a de-identified dataset, these IDs could create the capability to re-identify or link to additional data outside of intended use" (30 words). Another borderline case: "This article will outline what to consider when managing passthrough IDs and how to use the Datavant software to manage this data field" (25 words).
Jargon: Needs Attention - Several technical terms lack explanation for general audiences: "tokenization," "tokenized output," "de-identified dataset," "hashed IDs," "PHI" (though commonly understood in healthcare), and "expert determination." Consider adding brief definitions or a glossary link.
Active Voice: Mostly Pass - One passive construction: "A passthrough ID is a patient-level identifier that is passed through to the output of tokenization." Consider: "A passthrough ID is a patient-level identifier that passes through to the tokenization output."
Heading Clarity: Pass - Headings are clear and descriptive: "What is a Passthrough ID?" and "How to Manage Passthrough IDs" effectively preview content.
Link Text: Pass - Email links (support@datavant.com) provide clear context about their purpose within surrounding text.
Abbreviations: Needs Attention - "PHI" appears without expansion. Though common in healthcare, it should be written as "PHI (Protected Health Information)" on first use. "IDs" is acceptable as a standard abbreviation.
Overall WCAG Writing Score: Needs Attention
1. Break down long, multi-clause sentences into shorter statements. For example, "The Overlap Comparison tool is used to run multiple one-on-one overlaps at one time, overlapping the same base data table against multiple other tables and determining which pair has the most overlap" (33 words) could become: "The Overlap Comparison tool runs multiple one-on-one overlaps at once. It overlaps the same base data table against multiple other tables. It then determines which pair has the most overlap."
2. Simplify complex noun phrases and technical constructions. The phrase "All Assess tools default to computing unique individuals on Tokens 1 and 2" uses abstract technical language. Consider: "By default, all Assess tools count unique individuals using Tokens 1 and 2" or explain what "computing on tokens" means in plainer terms.
3. Reduce sentence complexity in procedural steps. The sentence "You can also use a table made available by request by clicking Request Access to the right of the table" contains nested prepositional phrases. Simplify to: "You can also request access to a table. Click Request Access on the right side of the table."
Plain Language: Needs Attention - Several instances of complex technical language without explanation: "computing unique individuals on Tokens 1 and 2," "pairwise overlap reports," "fill rates for tokens," and "patient cohort overall" assume technical knowledge.
Sentence Length: Needs Attention - Multiple sentences exceed 25 words:
- "The Overlap Comparison tool is used to run multiple one-on-one overlaps at one time, overlapping the same base data table against multiple other tables and determining which pair has the most overlap." (33 words)
- "Customers often use this report as way to quickly determine which potential partner table has the highest number of individuals in common with their own table." (27 words)
- "You can run Assess tools on available tables, including tables you own, tables shared with your organization, and On Demand tables." (21 words - acceptable but near limit)
Jargon: Needs Attention - Unexplained technical terms include:
- "Tokens 1 and 2" (partially explained but purpose unclear)
- "pairwise overlap reports"
- "fill rates"
- "patient cohort"
- "On Demand tables"
- "Token Exports"
Active Voice: Pass - Most instructions use active voice effectively ("Click Next," "Select the filters," "Generate and View Report"). One passive construction: "Overlap breakdowns are only available to select customers" could be "Only select customers can access overlap breakdowns."
Heading Clarity: Good - Step-by-step headings are clear and action-oriented (e.g., "Step 1. Generate an Overlap Report," "Step 2. Select a Base Table").
Link Text: Needs Attention - "The My Data Management page describes how to share your table" - the link text "My Data Management page" is good, but the sentence structure could be clearer about what is clickable.
Abbreviations: Pass - "FK" and "WCAG" are standard in context. Article uses full terms throughout.
Overall WCAG Writing Score: Needs Attention
The content meets the target readability threshold (below Grade 12), but here are three specific ways to improve it further:
1. Break down long technical noun phrases: Phrases like "record-by-record tokenization and token transformation" and "technical prerequisites" use multiple multi-syllable technical terms in sequence. Consider rewording to simpler constructions, such as "tokenizes and transforms records one at a time" and "technical requirements you need first."
2. Simplify administrative language: The credentials section uses formal language like "Each credential is valid for 10 years" and "You and any Admins on your account will receive email notifications as the credential nears expiration and when it has expired." Rewrite as: "Credentials last 10 years. You and your account admins get emails before and when they expire."
3. Replace complex vocabulary: Words like "prerequisite" (4 syllables), "infrastructure" (4 syllables), and "configuration" (5 syllables) appear frequently. Where possible, use simpler alternatives: "requirement" instead of "prerequisite," "system" instead of "infrastructure," and "setup" or "settings" instead of "configuration."
Plain Language: Needs Attention - Contains formal technical phrasing like "performs record-by-record tokenization and token transformation entirely on your infrastructure" and "extends the default 'file mode' of Datavant's software, providing greater flexibility." These could be simplified to more conversational language.
Sentence Length: Pass - Most sentences are well under 25 words. The breakdown shows an average of 13.6 words per sentence, which is excellent for readability.
Jargon: Needs Attention - Several technical terms lack explanation:
- "tokenization" (used extensively but not defined in this excerpt)
- "token transformation" (not explained)
- "PII" (acronym used without definition)
- "POST requests" (HTTP terminology assumed)
- "on-premise" (technical deployment term)
Abbreviations: Needs Attention -
- "CLI" - defined on first use as "Command Line Interface" (Good)
- "PII" - not defined (flag)
- "IP" - assumed knowledge (flag)
- "HTTP" - assumed knowledge (flag)
Active Voice: Mostly Pass - Generally uses active voice well. One passive construction found: "several Linux build options are available" could be "we offer several Linux build options."
Heading Clarity: Pass - Headings are clear and action-oriented using numbered steps ("Step 1. Complete Technical Prerequisites," "Step 3. Generate User Credentials"). This helps users navigate the process easily.
Link Text: Pass - No vague link text detected in the prose. References like "see Technical Requirements for the Datavant CLI" and "see Creating a Single Configuration" are descriptive.
Overall WCAG Writing Score: Needs Attention
The article has strong structural elements (sentence length, headings, active voice) but would benefit from defining technical terms and abbreviations, and simplifying some formal technical phrasing for better accessibility.
The content meets the Grade 12 target and is performing well. To improve readability further, consider these specific enhancements:
1. Break up compound sentences with multiple clauses. For example, "In batch mode, the CLI is installed on-premise and processes records in batches—either one file at a time or multiple files together" could become two clearer sentences: "In batch mode, the CLI is installed on-premise. It processes records in batches, either one file at a time or multiple files together."
2. Simplify technical phrases where possible. Replace "Complete technical prerequisites" with "Complete the setup requirements" and "Ensure input data conforms to validation rules" with "Make sure your input data follows the validation rules."
3. Reduce prepositional phrase stacking. The phrase "For more information on other deployment options for the Datavant tokenization software" contains nested prepositional phrases. Simplify to: "For more information about other ways to deploy Datavant tokenization software."
Plain Language: Needs Attention - Some phrases use unnecessarily complex constructions. Examples: "conforms to validation rules" (use "follows" or "meets"), "prerequisite" (use "requirement"), "nears expiration" (use "is about to expire").
Sentence Length: Pass - Most sentences are concise. The average of 13.2 words per sentence is excellent. All sentences appear to be well under the 25-word threshold.
Jargon: Needs Attention - Several technical terms lack explanation on first use: "on-premise," "tokenize," "transform," "de-identifying," "tokens for matching." While some are defined elsewhere, first-mention context would help.
Active Voice: Pass - The article predominantly uses active voice with clear imperative instructions: "Click Download," "Go to the Download page," "select Generate."
Heading Clarity: Pass - Headings follow a clear step-by-step structure (Step 1, Step 2, etc.) with descriptive action-oriented titles that tell users exactly what to do.
Link Text: Needs Attention - The article references links but uses vague phrases like "see Technical Requirements" and "see Creating a Single Configuration" without indicating these are clickable links. Use explicit link indicators or more descriptive link text.
Abbreviations: Needs Attention - "CLI" is expanded on first use (good practice), but the article text appears cut off mid-sentence at the end, suggesting "tra" may be an incomplete abbreviation or word.
Overall WCAG Writing Score: Needs Attention
The content successfully meets the readability target. Here are three specific suggestions to improve it further:
1. Break down compound technical processes: The sentence "When Datavant's applications request a secret, Secrets Manager: Fetches the encryption key. Transmits the secret securely over TLS." uses a colon-list format that could be clearer as a standard sentence or bulleted list. Consider: "When Datavant's applications request a secret, Secrets Manager performs two actions: it fetches the encryption key and transmits the secret securely over TLS."
2. Simplify multi-clause sentences: "Only a small group of Datavant team members can access this environment, and they cannot run Datavant software" could be split for clarity: "Only a small group of Datavant team members can access this environment. These team members cannot run Datavant software."
3. Add brief definitions for technical terms: While "TLS" and "encryption key" are standard security terms, consider adding parenthetical explanations on first use to support broader audiences, such as "Transmits the secret securely over TLS (Transport Layer Security, a security protocol)."
Plain Language: Needs Attention - Several phrases use technical jargon without explanation: "persistent storage," "tokens using a client's encryption scheme," and "TTP environment" (explained later but could be clearer upfront).
Sentence Length: Pass - Most sentences are concise. The longest sentence is approximately 22 words ("To communicate with Datavant's TTP AWS environment, you must configure your network when running Datavant CLI or Datavant Desktop"), which is acceptable.
Jargon: Needs Attention - Multiple unexplained technical terms: "secrets" (in security context), "TLS," "persistent storage," "tokens," "encryption scheme," "CLI." While appropriate for technical audiences, brief contextual definitions would improve accessibility.
Active Voice: Pass - The article predominantly uses active voice effectively: "Datavant uses," "AWS generates," "Secrets Manager encrypts," "Datavant runs."
Heading Clarity: Pass - The title clearly indicates the topic. Consider adding subheadings to break up the content (e.g., "How Secrets Manager Works," "Access Controls," "Network Configuration").
Link Text: Needs Attention - The phrase "see Technical Requirements to Run Datavant Software" is functional but could be more descriptive, such as "see network setup requirements for Datavant software."
Abbreviations: Needs Attention - Several abbreviations lack first-use expansion: "TLS," "AWS" (expanded once but not at first use), "CLI." "TTP" is expanded as "Trusted Third Party" which is good practice.
Overall WCAG Writing Score: Needs Attention
The content meets the target of Grade 12 or below and is appropriate for a technical audience. Here are three specific suggestions to improve readability further:
1. Break down long technical phrases into simpler constructs. For example, "Once you have provided your Delta Share ID, Datavant will share the Datavant Python Wheel + Sample Notebook to your account" could become "Provide your Delta Share ID to Datavant. We will then share the Python Wheel and Sample Notebook to your account."
2. Simplify compound sentences with multiple clauses. The sentence "Ensure that your single-user cluster is configured to best suit the amount of data and throughput" could be shortened to "Configure your single-user cluster for your data amount and throughput needs."
3. Add brief explanations for complex concepts before diving into instructions. For instance, before mentioning "Delta Sharing Catalog," add one simple sentence explaining what Delta Sharing is (e.g., "Delta Sharing is Databricks' method for secure data sharing between organizations").
Plain Language: Needs Attention - Some phrases could be simplified: "meant to be used as an accompaniment to" could be "use this guide with"; "requesting the SFTP delivery path with information on why" is unnecessarily complex and could be "explain why you need SFTP delivery."
Sentence Length: Pass - Most sentences are well under 25 words. The average of 16.7 words per sentence is excellent for comprehension.
Jargon: Needs Attention - Several technical terms lack explanation on first use:
- "Python wheel" (never explained)
- "distributed compute" (assumed knowledge)
- "Delta Share ID" (format shown but concept not explained)
- "SFTP" (acronym expanded would help)
- "LTS runtimes" (LTS not defined)
- "single-user cluster" (no context provided)
Abbreviations: Needs Attention - Unexplained abbreviations found:
- "LTS" (appears multiple times, never defined - likely "Long Term Support")
- "SFTP" (likely "Secure File Transfer Protocol" but not stated)
Active Voice: Pass - The article predominantly uses active voice ("upload it," "refer to," "verify network connectivity"). Minimal passive constructions present.
Heading Clarity: Good - Headings follow a clear numbered step format (Step 1, Step 2, etc.) which aids navigation and comprehension.
Link Text: Needs Attention - References to external resources lack specificity: "these steps" (vague - should describe what the steps do), "Troubleshooting section" (acceptable but article should confirm this section exists in the current document or specify it's external).
Overall WCAG Writing Score: Needs Attention
The article has strong structure and sentence length but needs work on defining technical terms, expanding abbreviations, and providing context for specialized concepts to meet WCAG 2.2 AAA accessibility standards.
The content meets the target readability threshold. Here are three specific suggestions to improve it further:
1. Break down compound sentences with multiple clauses. For example, "A Segment is a subset of data created from one or more parent tables" could become two sentences: "A Segment is a subset of data. It is created from one or more parent tables." Similarly, "Segments have the same behavior as tables and can be: Used in Assess for Profiles, Overlaps, Overlap Comparison, or Stack reports Shared with a Partner or set as On-Demand Distributed to a partner Pull advanced counts on a segmented table" should be restructured into shorter, parallel statements.
2. Simplify technical phrases where possible. Replace "subsetted table" with "filtered table" or "smaller table." Change "criteria from one table to filter matching patients in the secondary table" to "criteria from one table to find matching patients in the second table."
3. Reduce prepositional phrase chains. The sentence "In the top-right corner of the My Data page, click Create Segment" contains nested location phrases. Simplify to: "On the My Data page, click Create Segment in the top-right corner."
Plain Language: Needs Attention. Several instances of technical jargon compound complexity: "subsetted table," "token joins," "logic statement nesting," and "certified" (used without context). The phrase "Subsetting and segmentation of tables may increase risk of re-identification" uses abstract nominalizations that could be simplified.
Sentence Length: Pass. Most sentences stay under 25 words. The article maintains good sentence rhythm overall with an average of 18.4 words per sentence.
Jargon: Needs Attention. Several technical terms lack explanation:
- "Assess" (appears to be a tool name)
- "On-Demand" (capitalized, suggesting specific meaning)
- "token joins" (no definition provided)
- "de-identified and certified" (certification process unclear)
- "Inner Group" (technical term for logic nesting)
Active Voice: Needs Attention. Several passive constructions found:
- "Segments have the same behavior as tables and can be: Used in Assess..."
- "set as On-Demand"
- "Distributed to a partner"
- "must be enabled by the table owner"
- "A table that has been shared directly with you"
Heading Clarity: Pass. The article would benefit from visible headings in the cleaned text, but the procedural structure is clear and follows a logical sequence.
Link Text: Pass. The reference "What is a Table, Segment, and Data Group?" is descriptive. No vague "click here" links detected.
Abbreviations: Pass. No unexplained abbreviations or acronyms found in the text.
Overall WCAG Writing Score: Needs Attention
1. Break down compound sentences with multiple clauses. For example, "Customers often use Stack reports to understand the trade-offs in using different tables when compiling different resources for a project or use case" contains nested clauses that could be split: "Customers often use Stack reports to understand trade-offs in using different tables. This helps when compiling different resources for a project or use case."
2. Simplify multi-syllable technical phrases where possible. Replace phrases like "de-duplicated individuals" with "unique individuals" (which you already use elsewhere), and consider changing "cumulative pool" to "combined group" or defining it more clearly on first use.
3. Shorten procedural sentences with multiple instructions. The sentence "You can also use a table made available by request by clicking Request Access to the right of the table" (16 words) could be: "To use a table available by request, click Request Access. You'll find this to the right of the table."
Plain Language: Needs Attention - Some phrases are unnecessarily complex. "Cumulative pool," "de-duplicated individuals," "token matching criteria," and "running total number of de-duplicated individuals in your data pool" could be explained more clearly or defined on first use.
Sentence Length: Pass - Most sentences are under 25 words. The longest sentence is approximately 24 words ("Total Unique Individuals also displays a percentage, which represents the percentage of unique individuals that each data table contributes to the whole data pool"), which is acceptable.
Jargon: Needs Attention - Several technical terms lack explanation:
- "Tokens 1 and 2" (not explained what tokens are)
- "Token matching criteria"
- "De-duplicated individuals"
- "Patient cohort"
- "On Demand tables"
Active Voice: Pass - Most instructions use active voice effectively ("click Create Report," "Select up to 10 tables," "Drag and drop").
Heading Clarity: Good - Step-based headings are clear and descriptive ("Generate a Stack Report," "Select Tables," "Select Filters").
Link Text: Needs Attention - "The My Data Management page" appears to be a reference but lacks context about where to find it or what action to take.
Abbreviations: Pass - "WCAG" would need expansion in actual use, but no problematic abbreviations appear in this article text itself.
Overall WCAG Writing Score: Needs Attention
The content meets the target of Grade 12 or below, but here are three specific improvements to enhance readability further:
1. Simplify compound technical phrases: Replace phrases like "client-partner_TOKEN_ENCRYPTION_KEY" with a simpler introduction before use, such as "a special encrypted format called client-partner_TOKEN_ENCRYPTION_KEY" to add context before presenting the technical term.
2. Break down the command examples: The command-line examples like "cat [CREDENTIALS_FILENAME] | ./Datavant_Mac transform-tokens \" could benefit from brief explanations before or after, such as "This command reads your credentials file and transforms the tokens" to help readers understand what they're executing.
3. Clarify prerequisite relationships: The opening sentence "This article refers to the necessary steps needed before sharing data on the Datavant token" uses slightly redundant phrasing. Simplify to "This article explains the steps to share data using Datavant tokens" for directness and clarity.
Plain Language: Needs Attention - Several instances of unexplained technical jargon presented without context. Example: "client-partner_TOKEN_ENCRYPTION_KEY" appears without definition; "SFTP or S3" mentioned without expansion.
Sentence Length: Pass - Most sentences are concise. The longest sentence is "Once contracting is complete, support@datavant.com will have enabled a link to allow for data sharing between you and your partner" at 20 words, which is acceptable.
Jargon: Needs Attention - Multiple unexplained technical terms:
- SFTP (not expanded)
- S3 (not expanded)
- CLI (not expanded)
- client-partner_TOKEN_ENCRYPTION_KEY (not defined)
- "site key" (not explained)
- "linkable" (used in technical context without definition)
Active Voice: Needs Attention - Several passive constructions found:
- "tokens must be in a client-partner_TOKEN_ENCRYPTION_KEY"
- "the data will be in client-partner_TOKEN_ENCRYPTION_KEY"
- "Tokenised data is shared directly between partners" (appears twice)
Heading Clarity: Good - Headings follow a clear numbered step format (Step 1, Step 2, etc.) and describe the action needed. However, the article switches contexts ("Receiving Data In" section) without a clear heading to mark this transition.
Link Text: Needs Attention - Contains potentially vague link text:
- "Receiving Data In" (acceptable but could be more descriptive)
- "Onboarding User Guide" (acceptable)
- "Tokenization User Guide" (acceptable)
Email addresses used as links (support@datavant.com) which is acceptable for contact purposes.
Abbreviations: Needs Attention - Several abbreviations not expanded on first use:
- CLI (Command Line Interface)
- SFTP (Secure File Transfer Protocol)
- S3 (Amazon Simple Storage Service)
Overall WCAG Writing Score: Needs Attention
The content successfully meets the target readability level. Here are three specific suggestions to improve it further:
1. Simplify compound technical phrases: Replace phrases like "Ensure your machine or environment meets Datavant's technical requirements" with "Check that your computer meets Datavant's technical requirements" to reduce syllable count and increase clarity.
2. Break down the multi-step instruction under "Manage user access": The three sub-steps (a, b, c) contain dense information. Consider separating step "c" about permissions into its own numbered step, as "Configure application credentials" is conceptually different from user invitation.
3. Simplify the error explanation section: The phrase "This occurs when the application cannot create its required output directory due to missing read/write permissions" could be rewritten as "This happens when the application can't create its output folder because it lacks read/write permissions" to reduce complexity.
Plain Language: Needs Attention
- "Ensure that your input data conforms to Datavant's Tokenization Validation Rules" could be "Make sure your input data follows Datavant's Tokenization Validation Rules"
- "Default character encoding: UTF-8" assumes technical knowledge without explanation
Sentence Length: Pass
Most sentences are under 25 words and appropriately concise for instructional content.
Jargon: Needs Attention
Unexplained technical terms:
- "tokenizing/tokenization" (used throughout but never defined)
- "site encryption key"
- "output directory"
- "UTF-8" and other character encodings
- "flat file"
- "file delimiter"
Active Voice: Pass
Most instructions use active voice effectively (e.g., "Download and install," "Create a folder," "Ensure that").
Heading Clarity: Pass
Headings are clear and action-oriented, though the article appears to have formatting issues where heading text may have merged with body text.
Link Text: Pass
Link references are descriptive (e.g., "Managing Users for Your Company," "Technical Requirements for the Datavant CLI and Datavant Desktop").
Abbreviations: Needs Attention
- "CLI" - not explained on first use
- "ENOENT" - error code without explanation of what the acronym means
Overall WCAG Writing Score: Needs Attention
1. Break down complex sentences with multiple clauses. For example, "We recommend using the number of threads such that each process is at ~95% CPU usage without exceeding the number of cores on your machine" contains multiple technical conditions in one sentence. Split this into: "We recommend using multiple threads. Each process should run at ~95% CPU usage. Do not exceed the number of cores on your machine."
2. Simplify technical explanations with shorter, direct statements. The sentence "Datavant's applications are CPU-intensive, and the token creation and transformation processes are expensive, encryption-based operations" combines three concepts. Revise to: "Datavant's applications use a lot of CPU power. Token creation and transformation use encryption. These are resource-heavy operations."
3. Replace complex conditional phrasing with simpler alternatives. Change "When a PII element used to make a token is missing from the input, a valid token will not be generated" to "Missing PII elements result in error tokens, not valid tokens."
Plain Language: Needs Attention - Several instances of unnecessarily complex phrasing: "environments optimized for heavy computing," "encryption-based operations," "data quality statistics are surfaced in the data quality log"
Sentence Length: Needs Attention - Several sentences exceed 25 words:
- "We recommend using the number of threads such that each process is at ~95% CPU usage without exceeding the number of cores on your machine." (27 words)
- "When a PII element used to make a token is missing from the input, a valid token will not be generated." (19 words but grammatically complex)
Jargon: Needs Attention - Multiple technical terms lack explanation: "multithreading flag," "command line argument," "CPU-intensive," "encryption-based operations," "Cloud Provider native applications," "Snowflake Warehouse"
Active Voice: Pass - Most sentences use active voice effectively ("Ensure your machine is sized appropriately," "Turn off other background processes")
Heading Clarity: Pass - Questions are clear and specific, formatted as FAQ entries that directly match user concerns
Link Text: Needs Attention - Some link references are vague: "cloud performance articles" (should specify which articles), "the token error log" (could include hint about where to find it)
Abbreviations: Needs Attention - Several abbreviations introduced without full explanation on first use: "RAM," "CPU," "PHI/PII" (only used in heading, not explained)
Overall WCAG Writing Score: Needs Attention
1. Break up multi-step instructions into numbered lists. Currently, instructions appear as continuous prose (e.g., "Navigate to top menu Select Encoding > Convert to UTF-8 without BOM Save the file and reprocess"). Converting these to numbered steps would improve scannability and reduce cognitive load.
2. Simplify conditional phrasing. Sentences like "If you were unable to login, it's likey you do not have credentials to run Datavant Desktop" could be shortened to "Cannot login? You may not have credentials for Datavant Desktop." This reduces word count while maintaining clarity.
3. Convert passive constructions to active voice. Change "site credentials permissions were not provisioned to your account" to "Your Admin has not provisioned site credential permissions to your account." This creates clearer accountability and reduces sentence complexity.
Plain Language: Needs Attention - Some phrases are unnecessarily complex. "One of the main reasons for this error indicates the site credentials permissions were not provisioned" could be simplified to "This error usually means your site credentials were not set up."
Sentence Length: Pass - Most sentences are well within the 25-word limit. The average of 14.8 words per sentence is excellent for accessibility.
Jargon: Needs Attention - Several technical terms lack explanation:
- "provisioned" (used multiple times without definition)
- "BOM" (Byte Order Mark - unexplained abbreviation)
- "iso-8859-1" and "cp-1252" (encoding types mentioned without context)
- "ENOENT" (error code not explained)
Active Voice: Needs Attention - Several passive constructions found:
- "site credentials permissions were not provisioned"
- "If you were unable to login"
- "A configuration is required"
- "permissions were not provisioned"
Heading Clarity: Pass - Headings are clear and use question format effectively ("Why can't I see the options..."). Error messages are clearly labeled.
Link Text: Pass - References like "User Management page" and "Creating a Single Configuration" provide clear context about link destinations.
Abbreviations: Needs Attention - "BOM" appears without explanation. "CLI" is explained in the introduction but could benefit from being written out on first use in the main body.
Overall WCAG Writing Score: Needs Attention
The content meets the target readability level (below Grade 12), but could be improved further with these specific changes:
1. Break down compound sentences with multiple clauses. For example, "When running tokenize, the software standardizes certain fields so that formatting differences do not prevent tokens from linking across data tables" could become two sentences: "When running tokenize, the software standardizes certain fields. This ensures formatting differences do not prevent tokens from linking across data tables."
2. Simplify technical phrases. Replace "meet certain standardization requirements" with "meet specific format rules" and change "Ensure tokens are generated from input data that minimizes the risk of re-identification" to "Ensure tokens are generated from input data with low re-identification risk."
3. Use more concrete examples earlier. The Token 101 example is helpful but appears late in the article. Move practical examples like this higher up to illustrate abstract concepts like "validation rules" and "tokenization requirements" when they're first introduced.
Plain Language: Needs Attention
- "Data hygiene requirements" could be "data quality requirements"
- "Strict validation applies only to specific fields" is somewhat vague—specify which fields earlier
- "Flat file with UTF-8 character encoding" assumes technical knowledge that could be briefly explained
Sentence Length: Pass
Most sentences are well under 25 words. The longest sentence is approximately 22 words: "When running tokenize, the software standardizes certain fields so that formatting differences do not prevent tokens from linking across data tables."
Jargon: Needs Attention
Several technical terms lack explanation on first use:
- "tokens" (explained later but not immediately)
- "UTF-8 character encoding"
- "iso-8859-1" and "cp-1252"
- "Hadoop"
- "PII fields"
- "re-identification"
Active Voice: Pass
Most content uses active voice effectively ("Datavant does not apply," "Errors are flagged," "the software applies"). Passive constructions present are appropriate for technical context.
Heading Clarity: Pass
Headings are descriptive and hierarchical: "Overview," "Input data format," "Validation rules in tokenization" clearly signal content topics.
Link Text: Needs Attention
- "Onboarding Data Checks" - appears to be a link, acceptable
- "Reviewing the Tokenization Software Output and Log files" - good descriptive link text
- "support@datavant.com" - Pass (email address)
- "Reviewing the Tokenization" - appears cut off, incomplete link text
Abbreviations: Needs Attention
- "CLI" - not defined on first use (Command Line Interface)
- "PII" - not defined on first use (Personally Identifiable Information)
- "UTF-8" - not defined
Overall WCAG Writing Score: Needs Attention
The article has good structure and sentence length but needs to define technical abbreviations and jargon for broader accessibility. Adding brief definitions or a glossary link would significantly improve usability for readers less familiar with data tokenization terminology.
The content meets the target of Grade 12 or below, which is appropriate for technical documentation. Here are three specific suggestions to improve readability further:
1. Break down compound sentences with multiple clauses. For example: "CLI v5 provides expanded operating system support, support for Parquet file format, and compressed file support" could be split into: "CLI v5 provides expanded operating system support. It also supports Parquet file format and compressed files."
2. Simplify technical phrases where possible. The phrase "quality checks that assume deterministic outputs" could be rewritten as "quality checks that expect consistent, predictable results" or include a brief explanation of what "deterministic outputs" means in this context.
3. Convert some passive constructions to active voice. For example, "Removed in CLI v5" could become "CLI v5 removes this feature" and "Supported by server mode" could become "Server mode supports this feature."
Plain Language: Needs Attention - Terms like "deterministic token outputs," "cached data, reducing latency," "streamed in using standard output (stdout)," and "multiprocessing with available CPUs" lack plain language explanations for non-expert users.
Sentence Length: Pass - Most sentences are well under 25 words, with the average at 11.3 words per sentence.
Jargon: Needs Attention - Several unexplained technical terms appear: "SFTP file connection," "CLI binary," "server mode," "cached data," "latency," "standard output (stdout)," "batch mode," "multiprocessing," "deterministic outputs," "token outputs," "available cores."
Active Voice: Needs Attention - Multiple passive constructions found: "Removed in CLI v5," "Supported by server mode," "Replaced with --directory," "Displays as," "credentials are set."
Heading Clarity: Pass - Headings are clear and action-oriented ("Download the CLI v5 application," "Modify commands for CLI v5," "Review quality checks").
Link Text: Good - Link text "Troubleshooting CLI and Desktop - Error Messages" is descriptive and contextual.
Abbreviations: Needs Attention - "CLI" is not defined on first use, "SFTP" is not explained, "CPUs" appears without expansion, "v4" and "v5" use abbreviation without spelling out "version."
Overall WCAG Writing Score: Needs Attention
The content meets the Grade 12 target, but here are three specific improvements to enhance readability further:
1. Break down the long methodology paragraph: The paragraph beginning "The following charts illustrate Datavant's internal benchmarking results..." contains 62 words in a single sentence. Split this into 2-3 shorter sentences: "The following charts illustrate Datavant's internal benchmarking results. Tests ran on flat records across different configurations, operating systems, and thread counts. Each configuration ran 20 times on 100,000 dummy records."
2. Simplify technical phrases: Replace "shifts from being CPU-bound to I/O-bound" with clearer language like "shifts from processor limitations to input/output limitations" or add a brief explanation in parentheses to help non-expert readers.
3. Use consistent list formatting: The opening factors list uses sentence fragments mixed with full sentences. Standardize to either all complete sentences or all fragments: "Machine processing power" and "Number of CPUs" (fragments), or "The machine's processing power affects performance" (complete sentences).
Plain Language: Needs Attention - Terms like "CPU-bound," "I/O-bound," "flat records," and "thread counts" lack explanation for users unfamiliar with performance terminology.
Sentence Length: Flagged - One sentence exceeds 25 words: "The following charts illustrate Datavant's internal benchmarking results using flat records across different configurations, operating systems, and thread counts." (20 words but complex structure with multiple technical concepts)
Jargon: Needs Attention - Unexplained technical terms include: "flat records," "thread counts," "CPU-bound," "I/O-bound," "dummy records," "remediation procedures," "de-identification."
Active Voice: Pass - Most sentences use active voice effectively. Minor passive construction: "Average run time was converted" and "These values were then plotted" (acceptable in methodology context).
Heading Clarity: Pass - Headings clearly identify content sections (tokenize performance, transform-tokens performance, configuration questions).
Link Text: Pass - No link text present in provided content to evaluate.
Abbreviations: Needs Attention - "CLI" appears in headings without initial explanation; "ZIP," "ICD," "CPU," and "I/O" used without definition.
Overall WCAG Writing Score: Needs Attention
✓ Content meets readability target - Well done!
The article scores 10.3, which is comfortably below the Grade 12 threshold for technical writing. The average sentence length of 12.3 words is excellent and contributes significantly to this good score. The content balances necessary technical terminology with clear, concise sentence structure. Continue maintaining this approach in future documentation.
Plain Language: Needs Attention
- "Configuration specifications are stored securely in Datavant's cloud environment. They are accessed only while the software is running through the allowlisted api.datavant.com endpoint." - Consider simplifying "allowlisted endpoint"
- "expert determination" - HIPAA-specific term that could benefit from a brief explanation or link
Sentence Length: Pass
All sentences appear to be under 25 words. The average of 12.3 words per sentence is excellent for accessibility.
Jargon: Needs Attention
- "Tokenization" - defined contextually ✓
- "Onboarding" - defined contextually ✓
- "remediate/remediating" - used multiple times but never explicitly defined
- "PHI" - acronym used without definition
- "de-identification operations" - technical term not explained
- "allowlisted" - technical term not explained
- "connect key" and "transit key" - mentioned without explanation
Active Voice: Pass
Most sentences use active voice effectively. One minor instance: "are processed" and "are configured" could be rewritten, but they don't significantly impact clarity.
Heading Clarity: Pass
Headings are descriptive and follow a logical hierarchy: "Types of configurations," "Important Considerations," "Configuration files."
Link Text: Pass
References like "see Creating a Single Configuration" and "see Configuration Output Operations" provide clear context about link destinations.
Abbreviations: Needs Attention
- "PHI" - used without first spelling out "Protected Health Information"
- "HIPAA" - mentioned without spelling out "Health Insurance Portability and Accountability Act"
Overall WCAG Writing Score: Needs Attention
The article has strong sentence structure and organization, but would benefit from defining key abbreviations (PHI, HIPAA) on first use and explaining technical terms like "remediate" and "allowlisted" for readers who may be new to the platform.
The content meets the readability target of Grade 12 or below. To improve it further:
1. Break down complex compound sentences - The sentence "After selecting a trial tokenization project from the Project Dashboard, sponsors can view key trial information, track tokenization progress, and perform other trial management tasks" contains multiple clauses and ideas. Split this into two sentences: "Select a trial tokenization project from the Project Dashboard. You can then view key trial information, track tokenization progress, and perform other trial management tasks."
2. Simplify technical noun phrases - Replace phrases like "Full trial nameThis is the name as it appears in Datavant Trials Desktop Application or Datavant Trials Web Portal at Trial Sites" with shorter alternatives. Try: "Full trial name - Enter the name exactly as shown at Trial Sites in the Desktop Application or Web Portal."
3. Use simpler vocabulary where possible - Replace "reconciliation" with "matching" or "comparison," and "associated with" with "in" (e.g., "all trial sites in the trial" instead of "all trial sites associated with the trial").
Plain Language: Needs Attention - Some phrases are unnecessarily complex: "supports tracking and transparency of trial tokenization projects" could be "helps you track and view trial tokenization projects." The phrase "functions as a spoke" assumes knowledge of hub-and-spoke models without explanation.
Sentence Length: Pass - Most sentences are well under 25 words. The longest appears to be approximately 22 words, which is acceptable.
Jargon: Needs Attention - Several technical terms lack explanation:
- "tokenization" (used throughout but never defined)
- "tokens" (not explained in context)
- "SubjectIDs" (unexplained abbreviation/term)
- "hub-and-spoke model" (referenced but not defined)
- "CRO" (abbreviation not spelled out)
Abbreviations: Needs Attention
- "NCT #" (Clinical Trials Identifier Number is explained, but NCT itself is not)
- "CRO" (not expanded on first use)
- "UCSF" (used as an example without explanation that it's a university/hospital)
Active Voice: Pass - Most instructions use active voice effectively ("select," "view," "download," "send"). Passive voice is minimal and appropriate where used.
Heading Clarity: Pass - Headings are clear and task-oriented ("Access the Trials Project dashboard," "Set up a trial tokenization project," "Monitor tokenization by trial and by site").
Link Text: Pass - No hyperlinks present in the cleaned prose text to evaluate.
Overall WCAG Writing Score: Needs Attention
The content meets the target readability threshold (below Grade 12), which is appropriate for technical documentation. Here are three specific ways to improve readability further:
1. Break down compound technical sentences. For example, "The AWS Native Tokenization is a docker container built to be deployed on either ECS or EKS" could become two sentences: "The AWS Native Tokenization is a docker container. You can deploy it on either ECS or EKS." This separates the definition from the deployment information.
2. Simplify prepositional phrases. The phrase "It has added functionality to directly read from and write to S3 buckets in the account that the docker container is running in" contains nested prepositional phrases. Revise to: "It can read from and write to S3 buckets in your account."
3. Front-load action verbs in instructions. Change "Ensure any proxy server is set to pass-through mode" to "Set any proxy server to pass-through mode." This makes instructions more direct and reduces syllable count.
Plain Language: Needs Attention - Several instances of complex phrasing: "endpoints are accessible outbound over port 443," "pass through the incoming SSL certificate," "configured to pass back its own self-signed certificate." Consider defining or simplifying these technical phrases.
Sentence Length: Pass - Most sentences stay under 25 words. One borderline example: "If you have a proxy server, ensure it is configured to pass through the incoming SSL certificate from Datavant's endpoints, as opposed to passing back its own self-signed certificate" (30 words) - consider splitting.
Jargon: Needs Attention - Multiple unexplained technical terms: ECS, EKS, docker container, S3 buckets, SSL certificate, proxy server, pass-through mode, self-signed certificate, port 443, master salt, encryption keys. Consider adding brief definitions or linking to a glossary.
Active Voice: Pass - Generally uses active voice well in instructions ("Ensure," "Verify," "Create," "Click").
Heading Clarity: Good - Step-by-step headings are clear and action-oriented (e.g., "Step 1. Complete technical pre-requisites").
Link Text: Cannot assess - The cleaned prose doesn't show actual link text implementation, only references like "Download page" and "Configurations user guide."
Abbreviations: Needs Attention - AWS, ECS, EKS, CLI, SSL - none are defined on first use. Should expand: "Amazon Web Services (AWS)," "Elastic Container Service (ECS)," "Elastic Kubernetes Service (EKS)," "Command Line Interface (CLI)," "Secure Sockets Layer (SSL)."
Overall WCAG Writing Score: Needs Attention
The content meets the Grade 12 target successfully. To improve readability further:
1. Break down multi-clause sentences: The sentence "After you have prepared your data for the Match run and confirmed your matching threshold, contact the Datavant team with the details to begin the run" contains multiple dependent clauses. Simplify to: "First, prepare your data and confirm your matching threshold. Then contact the Datavant team to begin the run."
2. Simplify technical noun phrases: Replace dense phrases like "Profile Model Mapping is configured correctly on the onboarding tab of the configuration" with clearer alternatives such as "Set up the Profile Model Mapping correctly in the onboarding tab."
3. Replace complex verbs with simpler alternatives: Change "Optimizes for precision" to "Focuses on precision" and "initiating the run" to "starting the run" to reduce cognitive load.
Plain Language: Needs Attention - Some phrases are unnecessarily complex: "Ensure your Profile Model Mapping is configured correctly on the onboarding tab of the configuration" could be "Make sure you set up the Profile Model Mapping correctly."
Sentence Length: Pass - Most sentences stay under 25 words. The average of 15 words per sentence is excellent.
Jargon: Needs Attention - Several unexplained technical terms: "precision threshold," "recall," "tokenize," "tokens," "Profile Data Model," "DVID," "transit encryption key," "percentile" (in matching context). Consider adding brief definitions or linking to a glossary.
Active Voice: Pass - Mostly active voice used effectively. Minor passive construction: "has been converted" and "has been created" could be rewritten but don't significantly impact clarity.
Heading Clarity: Pass - Clear step-by-step structure with descriptive headings (Step 1-5).
Link Text: Needs Attention - Generic link phrases found: "For more information, see..." appears repeatedly. Replace with descriptive text like "Learn about precision thresholds in Understanding Match."
Abbreviations: Needs Attention - "DVID" appears without expansion on first use.
Overall WCAG Writing Score: Needs Attention
The content meets the target of Grade 12 or below. Here are three specific suggestions to improve readability further:
1. Break down complex compound sentences: The sentence "When an associated data table is updated with new records, either incrementally or in a full refresh, the Match run automatically runs to process the newly added records and to distribute DVIDs through the active distribution subscription" contains multiple clauses and ideas. Split this into two sentences: "When an associated data table is updated with new records (either incrementally or in a full refresh), the Match run automatically processes them. It then distributes DVIDs through the active distribution subscription."
2. Simplify technical explanations: The phrase "Match retains old records and their DVID assignments from previous dataset versions to minimize changes to existing DVIDs" could be rewritten more simply as "Match keeps old records and their DVID assignments. This minimizes changes to existing DVIDs."
3. Use bulleted lists for procedural information: The two-step process under "How does Match handle data updates?" ("If a match is found... If no match is found...") would be clearer as a numbered list format, making the logic flow more scannable and digestible.
Plain Language: Needs Attention - Some phrases are unnecessarily complex. Examples: "onboarding new records to a Match run with an active distribution" (use "adding"), "net new records" (use "new records"), "associated data table" (consider "linked data table").
Sentence Length: Pass - Most sentences are under 25 words. The longest is 32 words ("When an associated data table is updated with new records, either incrementally or in a full refresh, the Match run automatically runs to process the newly added records and to distribute DVIDs through the active distribution subscription") but this is an isolated case.
Jargon: Needs Attention - Several technical terms lack immediate explanation: "data pool" (explained in context), "incremental" and "full refresh" (defined), "tokens" (not explained), "SFTP location" (not explained), "ingestion pipelines" (not explained). Consider adding brief explanations for tokens, SFTP, and ingestion pipelines.
Active Voice: Good - The article predominantly uses active voice. Examples: "Match aims to preserve," "Match identifies net new records," "Datavant distributes updated DVIDs." One passive construction appears: "updates are delivered as a separate file" but this is acceptable in context.
Heading Clarity: Good - Headings are descriptive and action-oriented: "Add data to a Match data pool," "How does Match handle data updates?" These clearly indicate content that follows.
Link Text: Pass - The article references "Understanding Match" and "support@datavant.com" which are appropriately descriptive. No vague "click here" or "read more" links present.
Abbreviations: Good - Abbreviations are properly introduced: "Datavant IDs (DVIDs)" on first use, then DVID throughout. "SFTP" appears without expansion and should be defined as "Secure File Transfer Protocol" on first use.
Overall WCAG Writing Score: Needs Attention
The content meets the Grade 12 target, but here are three specific ways to improve readability further:
1. Simplify compound procedural phrases: Replace phrases like "you will be presented with two options" with "you'll see two options" and "Select whether you'd like this data dictionary to be saved" with "Choose to save this data dictionary." These shorter constructions reduce syllable count while maintaining clarity.
2. Break down the complex Step 2a instructions: The paragraph beginning "Here you can upload the data dictionary..." contains dense technical requirements. Split this into bulleted requirements: "Your data dictionary must meet these requirements:" followed by separate bullets for format, header requirements, and column requirements.
3. Reduce nested conditional statements: The sentence "If you created a configuration for tokenization, select that configuration here" appears amid other instructions. Group all conditional "if" statements separately from action steps to reduce cognitive load and simplify sentence structures.
Plain Language: Needs Attention - Some unnecessarily complex phrases found: "onboarding data to the Datavant Connect Platform" (could be "adding data to"), "indication" (undefined context), "remedy this" (could be "fix this").
Sentence Length: Pass - Most sentences are appropriately short. One borderline example at 24 words: "Here you can upload the data dictionary with table names and variable columns."
Jargon: Needs Attention - Several unexplained technical terms: "Portal Expert Determination," "tokenization," "configurations," "data dictionary," "multi-tab xslx," "newline-separated rows," "prefix or suffix." While some may be necessary for the technical audience, first-use definitions would improve accessibility.
Active Voice: Pass - Predominantly uses active voice and direct commands ("Select," "Click," "Enter"), which is appropriate for procedural documentation.
Heading Clarity: Good - Clear step-based structure (Step 1, Step 2, Step 2a, Step 2b, Step 3) that helps users navigate the workflow logically.
Link Text: Needs Attention - Contains vague link text: "here" (in "access it here") and "see from Step 4" are not descriptive of destination content. Should be "watch the Portal Expert Determinations demo" and "start at Step 4 of the Privacy Hub Data Upload guide."
Abbreviations: Needs Attention - ".csv" and "xslx" appear without explanation on first use. "FK" isn't in the article but technical abbreviations should be spelled out on first reference.
Overall WCAG Writing Score: Needs Attention
The content meets the readability target (below Grade 12), but could be improved further with these specific changes:
1. Break down complex multi-clause sentences: The sentence "These settings are required for the user performing tokenization. They grant that user permission to download and run the software." could be combined more clearly as: "Enable these settings to grant tokenization users permission to download and run the software." This reduces unnecessary sentence breaks while maintaining clarity.
2. Simplify technical phrases: Replace compound technical phrases like "Ensure that the input data you use for tokenization conforms to Datavant's Tokenization validation rules" with shorter alternatives such as: "Check that your input data follows Datavant's validation rules." This reduces word count and cognitive load.
3. Convert long descriptive statements into simpler constructs: The phrase "Does your machine and your environment met the required Datavant technical requirements to run the software successfully on-premise?" contains 19 words. Simplify to: "Does your machine meet Datavant's technical requirements?" (8 words), then list requirements separately.
Plain Language: Needs Attention - Several phrases use unnecessarily complex constructions. Examples: "conforms to Datavant's Tokenization validation rules" (use "follows" instead of "conforms to"), "the user responsible for running" (use "the user who runs").
Sentence Length: Pass - Most sentences are well under 25 words. The average is 11 words per sentence, which is excellent for accessibility.
Jargon: Needs Attention - Multiple technical terms lack explanation or context:
- "tokenization" (used throughout, never defined)
- "site encryption key" (no explanation of what this is)
- "flat file" (technical term without definition)
- "quoting level" (unexplained)
- "UTF-8 character encoding" and "ISO-8859-1" (no context for non-technical users)
- "delimiter" (technical term)
Active Voice: Needs Attention - Several passive constructions found:
- "It's recommended to tokenize" → "We recommend tokenizing"
- "This is available from the Download page" (appears twice) → "Download this from the Download page"
- "These settings are required" → "You need these settings"
Heading Clarity: Needs Attention - Some headings are unclear standalone statements: "Machine and environment" should be a question or instruction like "Check machine and environment requirements." "Enable application settings" lacks context about what settings or why.
Link Text: Pass - Link references like "Use Datavant CLI in Batch Mode," "Managing Users for Your Company," and "Datavant CLI Commands and Optional Arguments" are descriptive and meaningful.
Abbreviations: Needs Attention - "CLI" is used throughout but never expanded on first use (should be "Command Line Interface (CLI)"). "UTF-8," "ISO," and "cp-1252" are unexplained abbreviations.
Overall WCAG Writing Score: Needs Attention
The content meets the readability target. Here are three specific suggestions to improve it further:
1. Break down compound sentences with multiple clauses. For example: "Datavant's tokenization engine creates tokens, or de-identified patient keys, from different permutations of patient demographics, such as name, date of birth, gender, and social security number" could be split into two sentences: "Datavant's tokenization engine creates tokens (de-identified patient keys). These tokens are generated from patient demographics such as name, date of birth, gender, and social security number."
2. Simplify the operation definitions. The three operations (tokenize, transform-tokens to, transform-tokens from) are described in very dense sentences with semicolons. Each definition should be its own short paragraph with the action separated from the context. For example, split "creates transit tokens by transforming tokens from a site-specific encryption key to a transit encryption key that is specific to the sender and intended recipient; run by sites prior to sending any tokens outside their environment to partners" into two sentences.
3. Replace technical phrases with simpler alternatives where possible. For instance, "appropriately sized" could be "large enough," and "accessible outbound over port 443" could be explained more plainly as "accessible for outgoing connections on port 443."
Plain Language: Needs Attention - Heavy use of technical jargon without upfront definitions. Terms like "transit encryption key," "site-specific encryption key," "de-identification operations," and "downstream linking" appear without context or explanation.
Sentence Length: Pass with caution - Most sentences are under 25 words due to good average sentence length (14.0 words). However, several complex sentences exist, such as: "The tokenization engine comes in several modes that, depending on your requirements and use case, can be deployed on-premise or in the Datavant cloud" (24 words but densely packed).
Jargon: Needs Attention - Unexplained technical terms include: "tokenization engine," "de-identified patient keys," "patient demographics," "transit tokens," "site-specific encryption key," "transit encryption key," "CLI," "batch mode," "on-premise," "proxy server," "pass-through mode," "cryptographic secrets," "master salt."
Active Voice: Pass - The article predominantly uses active voice ("creates tokens," "run by sites," "install the CLI"). Minimal passive constructions found.
Heading Clarity: Good - Headings like "Determine How to Use the Datavant Tokenization Engine" and "Step 1. Complete technical pre-requisites for on-premise software" clearly indicate content that follows.
Link Text: Cannot assess - The cleaned prose text doesn't indicate how links are formatted in the original article (e.g., "refer to Use Datavant CLI in Batch Mode" may be a link but context is unclear).
Abbreviations: Needs Attention - "CLI" is defined on first use (Command Line Interface), but "OS" is not defined. "RAM," "GHz," and version abbreviations ("v18.04.6") are used without explanation.
Overall WCAG Writing Score: Needs Attention
This content meets the Grade 12 target, but here are three specific ways to improve readability further:
1. Reduce multi-syllable business jargon: Replace phrases like "conducts analytics on data" with simpler alternatives like "analyzes data" and "aggregates data" with "collects and combines data" to reduce syllable count and improve clarity.
2. Add context to abbreviated concepts: The phrase "licensing data or bringing in data into your environment" assumes technical knowledge. Simplify to "licensing data or importing data into your company's systems" and consider explaining what "licensing data" means for non-technical users.
3. Break up the repetitive structure: The article uses "You are a company that..." 16 times consecutively. While this creates scannable content, varying the structure (e.g., "Select this if your company...", "Choose this option when you...", or using a bulleted format with category headers) would improve engagement and comprehension.
Plain Language: Needs Attention - Terms like "aggregates data," "licensing data," "consulting overlay," "Clinical Research Organization," and "health insurance company" lack plain language definitions. "HUB services" is industry-specific jargon that needs explanation.
Sentence Length: Pass - All sentences are well under 25 words. The average of 10.4 words per sentence is excellent for accessibility.
Jargon: Needs Attention - Unexplained technical terms include: "analytics," "licensing data," "data products," "data marketplace," "Clinical Research Organization," "diagnostics company," "HUB services," and "consulting overlay."
Active Voice: Pass - The article consistently uses active voice with clear subject-verb structure ("You are a company that...").
Heading Clarity: Needs Attention - The article appears to lack structural headings to organize the different company types and industry types. Adding headings like "Company Type Definitions" and "Industry Type Definitions" would significantly improve navigation.
Link Text: Cannot assess - No link text present in the provided content.
Abbreviations: Needs Attention - "HUB" appears without explanation. "CRO" is spelled out as "Clinical Research Organization" but could benefit from showing the abbreviation in parentheses for clarity.
Overall WCAG Writing Score: Needs Attention
The content meets the target readability level (below Grade 12), which is good for technical documentation. Here are three specific suggestions to improve it further:
1. Expand abbreviated terms on first use: Instead of "GUI (graphical user interface) that wraps around the CLI (command-line interface)", write "graphical user interface (GUI) that wraps around the command-line interface (CLI)" to reduce cognitive load and improve clarity.
2. Simplify compound technical phrases: The phrase "review and complete the technical prerequisites required for on-premises requirements" contains redundant phrasing. Simplify to "review and complete the technical prerequisites for on-premises installation" to reduce syllable count and improve clarity.
3. Break down the multi-clause sentence: "This is the encryption key that the user is allowed to access when running the Datavant tokenization software" could be split into two shorter sentences: "This is the encryption key for the user. They can access it when running the Datavant tokenization software."
Plain Language: Needs Attention - Several instances of technical jargon appear without sufficient context. Examples: "wraps around the CLI," "processes flat files in batches," "toggle on the permission," and "de-identifying data" assume reader familiarity with technical concepts.
Sentence Length: Pass - The average sentence length is 12.5 words, well below the 25-word threshold. Most sentences are appropriately concise for technical documentation.
Jargon: Needs Attention - Multiple unexplained technical terms: "flat files," "batches," "engine," "on-premise," "toggle," "de-identifying," "site encryption key," "validation rules," "re-identification," "tokens for matching." While GUI and CLI are explained, many other technical terms are not.
Active Voice: Pass - The article predominantly uses active voice and imperative mood appropriate for procedural documentation (e.g., "Contact your Site Admin," "Click the Download link," "Select the user").
Heading Clarity: Pass - Headings are clear, numbered sequentially, and use action-oriented language that describes the task (e.g., "Download the application," "Generate user credentials," "Create a configuration").
Link Text: Needs Attention - "For more information, see The Datavant Tokenization Software" and similar phrases use vague "see" and "for more information" patterns. Better practice would be descriptive link text like "Learn about Datavant tokenization software deployment methods."
Abbreviations: Needs Attention - "GUI" and "CLI" are explained on first use (good), but "Admin" appears as an abbreviation of "Administrator" without explanation. The article text also appears truncated at "Step 6. Ensure input data is" suggesting incomplete content.
Overall WCAG Writing Score: Needs Attention
The content successfully meets the Grade 12 target, but these improvements would enhance readability further:
1. Simplify compound sentences with multiple clauses. For example, "Learn how to license mortality sources that overlap with a base cohort of interest. For example, a cohort of study patients you have already tokenized." could become two simpler sentences: "Learn how to license mortality sources that overlap with a base cohort. A base cohort might be study patients you have already tokenized."
2. Break down the long definition in the Overview. The sentence "For researchers outside the United States and Canada, an obituary is a formal notice of death, usually published in a newspaper, that includes a brief biography of the deceased" contains multiple descriptive elements. Consider: "For researchers outside the United States and Canada: An obituary is a formal notice of death. It usually appears in a newspaper. It includes a brief biography of the deceased."
3. Reduce word density in technical explanations. The phrase "These resources explain how to determine which sources provide the largest possible pool of individuals for your use case" could be simplified to "These resources help you find which sources have the most relevant individuals for your project."
Plain Language: Needs Attention - Some complex phrases found: "presumed date of death to individuals aged 125 years or older" could be "assumed death date for people 125 or older"; "data source deliverables" could be "what you receive"
Sentence Length: Pass - Most sentences are well under 25 words. The longest sentence is approximately 22 words, which is acceptable.
Jargon: Needs Attention - Several technical terms lack explanation:
- "tokenized" (appears without definition)
- "Stack Report" (context-specific tool name)
- "base cohort" (used before clear definition)
- "Death Master File" (acronym context unclear initially)
Active Voice: Pass - Predominantly uses active voice with clear subject-verb constructions. Occasional passive voice is appropriate for context (e.g., "Deaths reported each week").
Heading Clarity: Good - Headings are descriptive and follow logical progression: "Overview," "Assess mortality sources," "Data source deliverables"
Link Text: Pass - Link descriptions are contextual and meaningful (e.g., "Run a Stack Report of Overlapping Patients," "Understanding Assess")
Abbreviations: Needs Attention - "ssa.gov" appears without spelling out "Social Security Administration" first in that sentence, though it is mentioned in full earlier in the same paragraph.
Overall WCAG Writing Score: Needs Attention
The content successfully meets the Grade 12 target readability threshold. To improve clarity further:
1. Break down technical compound sentences: The sentence "By integrating a Datavant-owned IAM Role to a customer Snowflake account, Snowflake can write directly to the Datavant S3 bucket" combines multiple technical concepts. Consider: "First, integrate a Datavant-owned IAM Role to your Snowflake account. This allows Snowflake to write directly to the Datavant S3 bucket."
2. Simplify process descriptions: The phrase "This direct transfer from a Snowflake account to an Datavant S3 account streamlines the distribution process for data onboarding" uses complex vocabulary. Consider: "This direct transfer makes data onboarding faster and simpler."
3. Add transition phrases between steps: The article jumps directly from technical instructions to new steps. Adding brief context statements like "Now that the role is created, the next step is..." would improve flow and comprehension for readers following the multi-step process.
Plain Language: Needs Attention - Phrases like "streamlines the distribution process" and "retrieve the Account ID used by Snowflake for the storage integration" could be simplified. Consider "makes the process faster" and "get the Account ID that Snowflake uses."
Sentence Length: Pass - All sentences are under 25 words, with the longest being approximately 24 words. Average sentence length of 15.4 words is well within acceptable range.
Jargon: Needs Attention - Several technical terms lack explanation:
- IAM Role (not explained on first use)
- S3 bucket/prefix (assumed knowledge)
- Storage integration (not defined)
- ARN (not defined)
- External ID (purpose unclear)
- Stage (Snowflake-specific term not explained)
Abbreviations: Needs Attention - Multiple unexplained abbreviations:
- IAM (Identity and Access Management)
- ARN (Amazon Resource Name)
- AWS (Amazon Web Services)
- S3 (Simple Storage Service)
- DESC (Describe command)
Active Voice: Good - Most instructions use active voice ("Create an IAM Role," "Run this command," "Replace the angled brackets"). One passive construction: "A success message displays to confirm the integration" could be "You will see a success message."
Heading Clarity: Needs Attention - The "Overview" heading has no actual heading markup in the text (appears as "OverviewBy" - likely a formatting error). Step headings are clear and descriptive.
Link Text: Cannot Assess - References to "Download page" appear without actual link text visible in the cleaned prose, so cannot evaluate if links are descriptive.
Overall WCAG Writing Score: Needs Attention
The article has good sentence structure and active voice, but requires glossary support for technical terms and abbreviations, plus minor improvements to plain language phrasing.
The content successfully meets the target reading level. Here are three specific suggestions to improve readability further:
1. Break down the long compound sentence in the opening paragraph. The sentence "This solution enables pre-sales feasibility and evaluation of datasets via the Datavant Connect Web Platform while the data remains in each source's respective AWS environment" could be split into two clearer sentences: "This solution enables pre-sales feasibility and evaluation of datasets via the Datavant Connect Web Platform. The data remains in each source's respective AWS environment."
2. Simplify technical phrases where possible. Replace "establishing a connection between an IAM role in your organization's AWS account and your organization's Datavant Connect company" with "connecting your AWS IAM role to your Datavant Connect company" to reduce redundancy and complexity.
3. Convert the nested prerequisite about permissions into plainer language. Change "Your organization has permissions in the Datavant Connect platform to onboard and assess tables stored in AWS. Datavant will configure this permission for you." to "Datavant will configure the required permissions for you to onboard and assess AWS-stored tables."
Plain Language: Needs Attention - Several phrases use unnecessary complexity: "pre-sales feasibility and evaluation" could be "testing and evaluation"; "respective AWS environment" could be "own AWS environment"; "establishing a connection between" could be "connecting."
Sentence Length: Pass - All sentences are under 25 words. The longest sentence contains approximately 23 words, which is acceptable.
Jargon: Needs Attention - Multiple unexplained technical terms: IAM role, AWS Account ID, AWS Role ARN, ARN, inline policies, environment-specific resources, encryption key, tokenized. While some technical terms are unavoidable for this audience, brief definitions or links to explanations would improve accessibility.
Active Voice: Pass - The article primarily uses active voice effectively ("click Settings," "Select the checkbox," "Fill in the necessary information").
Heading Clarity: Good - Headings are descriptive and clearly structured: "Overview and Prerequisites," "Establish the AWS Connection," and "Troubleshooting" all indicate what content follows.
Link Text: Needs Attention - "IAM Role User Guide" and "IAM User Guide" appear to be references but lack actual hyperlinks in the provided text. If these are meant to be links, they should be implemented. The phrase "reach out to" lacks a link to contact information.
Abbreviations: Needs Attention - Several unexplained abbreviations: AWS (first use should spell out "Amazon Web Services"), IAM (should spell out "Identity and Access Management"), ARN (should spell out "Amazon Resource Name") on first use.
Overall WCAG Writing Score: Needs Attention
The content meets the target readability level. Here are three specific suggestions to improve it further:
1. Break down compound instructions: The sentence "Run tokenize and transfer-tokens --to datavant so that your table will be in the correct transit encryption key to onboard to Datavant" combines multiple technical concepts. Consider breaking this into two sentences: "Run tokenize and transfer-tokens --to datavant. This ensures your table uses the correct transit encryption key for Datavant onboarding."
2. Simplify the requirements section: The phrase "There are several requirements necessary to ensure successful use of the onboard subcommand via the CLI" could be shortened to "You need to meet several requirements to use the onboard subcommand successfully."
3. Clarify the file size guidance: The sentence "The ideal file size to use the Onboard Subcommand is anything <1GB" uses technical shorthand. Spell it out: "The ideal file size to use the Onboard Subcommand is anything under 1 gigabyte (GB)."
Plain Language: Needs Attention - Some phrases use unnecessary complexity: "streamline your process to more seamlessly leverage" could be "simplify your process to use"; "requirements necessary to ensure successful use" could be "requirements to use successfully"
Sentence Length: Pass - All sentences are under 25 words with good average length of 14.3 words per sentence
Jargon: Needs Attention - Multiple unexplained technical terms: "tokenized tables," "transit encryption key," "SFTP," "packet/buffer size," "whitelist," "ingestion process." While some technical terms are unavoidable, consider adding brief explanations or links for the more complex concepts.
Active Voice: Pass - Article primarily uses active voice with clear commands ("Run tokenize," "Contact your Customer Success lead," "Create both your configuration")
Heading Clarity: Pass - Headings are descriptive and follow a logical progression (Overview → Technical Requirements → Running onboard → Monitor Data Onboarding)
Link Text: Needs Attention - "Refer to Troubleshoot Table Import Errors and Onboarding Data Checks" - unclear if these are links or section references. If links, they should be formatted as actionable link text within context.
Abbreviations: Needs Attention - "CLI" (Command Line Interface), "SFTP" (Secure File Transfer Protocol), and "GB" (Gigabyte) appear without first being spelled out. On first use, write "Command Line Interface (CLI)" for clarity.
Overall WCAG Writing Score: Needs Attention
The content successfully meets the target grade level of 12 or below. To improve readability further, consider these specific refinements:
1. Break down compound sentences with multiple clauses. For example, "The output from transform-tokens from is a file (or files) in which the tokens have been transformed, or re-encrypted, from a transit encryption key that is shared between your site and your partner site, to your site-specific encryption key" contains multiple embedded clauses. Split this into: "The output from transform-tokens from is a file (or files) with transformed tokens. These tokens have been re-encrypted from a transit encryption key to your site-specific encryption key. The transit key is shared between your site and your partner site."
2. Simplify technical compound nouns. Phrases like "site-specific encryption key" and "transit encryption key" appear repeatedly. Consider introducing a shorthand after first use (e.g., "site key" and "transit key") or creating a glossary box to reduce cognitive load.
3. Make the "Overview" section more scannable. The opening paragraph contains several distinct ideas (recommendation to review output, error handling, article purpose, troubleshooting resources). Break this into 2-3 shorter paragraphs with clear topic sentences to improve comprehension.
Plain Language: Needs Attention - Some sentences use complex constructions. Example: "Note that the output from the on-premise application depends on which operation you've run, and any errors will be sent to the console (if console output is enabled) and will also be visible in the dev log" could be simplified to separate ideas more clearly.
Sentence Length: Needs Attention - Several sentences exceed 25 words:
- "Datavant always recommends reviewing the output after running the Datavant tokenization software as it's important to check the appropriate remediations are applied and ensure high-quality and valid tokens are included in the output file(s)." (32 words)
- "While Datavant performs some basic format checks on the fields that are processed, some fields (e.g. clinical values) may be configured to pass through without modification." (28 words)
- "The output from transform-tokens from is a file (or files) in which the tokens have been transformed, or re-encrypted, from a transit encryption key that is shared between your site and your partner site, to your site-specific encryption key." (42 words)
Jargon: Needs Attention - Several technical terms lack explanation on first use:
- "remediations" (used multiple times without definition)
- "tokenization" (assumed knowledge)
- "PHI values" (acronym explained nowhere in the visible text)
- "transit encryption key" vs "site-specific encryption key" (the distinction is unclear)
- "dev log" (abbreviation of "development"?)
Active Voice: Needs Attention - Multiple passive constructions found:
- "is available on limited release" → "we offer on limited release"
- "will be sent to the console" → "the system sends to the console"
- "has had remediations applied to it" → "includes applied remediations"
- "has been transformed appropriately" → "you have transformed appropriately"
Heading Clarity: Pass - Headings clearly describe content sections (Outputs, Tokenize, Transform-tokens to/from, Dev Log File)
Link Text: Pass - Email addresses are descriptive (support@datavant.com). Reference to "available troubleshooting articles" could be more specific if it's an actual link.
Abbreviations: Needs Attention - Unexplained abbreviations found:
- "PHI" (Protected Health Information - should be spelled out on first use)
- "CLI" (Command Line Interface - mentioned but not explained)
- "v5" (version 5 - clear from context but could be spelled out)
Overall WCAG Writing Score: Needs Attention
The content meets the target readability level (below Grade 12). To improve it further:
1. Break down compound sentences with multiple clauses. For example, "This approach works best when: Records are immutable once created. You do not need to update or delete previously onboarded records." could be simplified to shorter, standalone sentences rather than nested conditions.
2. Simplify technical phrases. Replace "Your dataset contains ADDs, CHANGEs, and DELETEs" with "Your dataset has new records (ADDs), updated records (CHANGEs), and removed records (DELETEs)" on first use to make the capitalized terms clearer immediately.
3. Reduce multi-syllable words where possible. Consider: "harmonizing" → "combining" or "merging", "manageability" → "ease of handling", "continuously" → "constantly" or "always", and "automatically and permanently" → "permanently" (one adverb is sufficient).
Plain Language: Needs Attention - Terms like "immutable," "harmonizing," "append-only," and "inline" may not be clear to all users. Consider defining or replacing these terms.
Sentence Length: Pass - Most sentences are concise. One longer sentence: "You are responsible for harmonizing ADDs, CHANGEs, and DELETEs in your source system so that the dataset you provide to Datavant represents the current point-in-time state" (29 words) - consider breaking after "source system."
Jargon: Needs Attention - Unexplained technical terms include: "append-only," "immutable," "harmonizing," "inline," "point-in-time state," and "throughput." These should be defined on first use or glossed in context.
Active Voice: Pass - Article predominantly uses active voice effectively. Only minor passive construction: "An import is defined as all files that are dropped" - could be "We define an import as all files dropped."
Heading Clarity: Pass - Headings are clear and descriptive: "Should my table be full refresh or incremental?", "When to Use Incremental Refresh", "Best Practices for Efficient Data Uploads" all clearly signal content.
Link Text: Pass - Link text appears descriptive: "General Onboarding User Guide" clearly indicates destination (though this is the only link present).
Abbreviations: Needs Attention - "ADDs," "CHANGEs," and "DELETEs" are used as abbreviations/shorthand without initial explanation. "MB" and "GB" are used but are sufficiently common. The capitalized terms should be explained: "ADDs (additions)," "CHANGEs (modifications)," "DELETEs (removals)."
Overall WCAG Writing Score: Needs Attention
The content successfully meets the readability target of Grade 12 or below. To improve readability further:
1. Break up the long introductory sentence (45 words): "This guide applies to organizations that are implementing Datavant Connect Discovery Cloud in AWS. This solution enables pre-sales feasibility and evaluation of datasets via the Datavant Connect Web Platform while the data remains in each source's respective AWS environment." Consider splitting this into 2-3 shorter sentences, each focusing on one concept (what it applies to, what it enables, where data stays).
2. Simplify technical phrasing: Replace "pre-sales feasibility and evaluation of datasets" with plainer alternatives like "testing and reviewing datasets before purchase" to reduce cognitive load and syllable count.
3. Add transition words to Step 3: The sentence "If you have chosen two tables to query, be sure to specify the join between the tables" could be softened to "When you choose two tables, remember to specify how they join together" for improved flow and clarity.
Plain Language: Needs Attention - Terms like "pre-sales feasibility," "allowlist," and "join between the tables" may not be clear to all users without context.
Sentence Length: Flag - The opening sentence contains 45 words, nearly double the 25-word guideline: "This guide applies to organizations that are implementing Datavant Connect Discovery Cloud in AWS. This solution enables pre-sales feasibility and evaluation of datasets via the Datavant Connect Web Platform while the data remains in each source's respective AWS environment."
Jargon: Flag - Several unexplained technical terms: "AWS," "allowlist," "SQL query," "join" (database context), "Report Request flow"
Active Voice: Pass - Most sentences use active voice appropriately ("go to," "click," "select," "enter").
Heading Clarity: Pass - Step-by-step headings are clear and action-oriented.
Link Text: Pass - No links present in the cleaned prose text (email address is informational, not a vague link).
Abbreviations: Flag - "AWS" and "SQL" are not defined on first use.
Overall WCAG Writing Score: Needs Attention
The content meets the readability target, but here are 3 specific suggestions to improve it further:
1. Break up the longest sentence (35 words): "This article is for organizations implementing Datavant Connect Discovery Cloud in AWS. The solution enables pre-sales feasibility assessments and dataset evaluations through the Datavant Connect Web Platform, while ensuring that all data remains securely within each source's AWS environment." Split this into shorter, more digestible sentences by separating the description of what the solution enables from the security assurance.
2. Simplify technical noun phrases: Replace "pre-sales feasibility assessments and dataset evaluations" with simpler alternatives like "feasibility checks and data reviews" or define these terms more clearly when first introduced.
3. Add brief explanations for technical concepts: Terms like "Glue Database," "Glue Table," and "table allowlists and blocklists" appear without context. Adding one-sentence explanations (e.g., "Glue Tables (AWS's data catalog system)") would improve comprehension without significantly affecting the FK score.
Plain Language: Needs Attention - Phrases like "pre-sales feasibility assessments," "dataset evaluations," and "de-identified or not covered under HIPAA" use complex terminology that could be simplified or explained.
Sentence Length: Flag - One sentence exceeds 25 words: "The solution enables pre-sales feasibility assessments and dataset evaluations through the Datavant Connect Web Platform, while ensuring that all data remains securely within each source's AWS environment." (29 words)
Jargon: Needs Attention - Unexplained technical terms include: IAM Role, Glue Database, Glue Table, Site Name (in the context of encryption), allowlists/blocklists, de-identified, HIPAA compliance, Overlap report, Profile report, and custom SQL queries.
Active Voice: Pass - The article predominantly uses active voice with clear imperative instructions ("Log in," "Click," "Complete," "Enter").
Heading Clarity: Pass - Headings are clear and descriptive ("Overview and Prerequisites," "Register a Table with AWS"), though the main heading could be more action-oriented.
Link Text: Pass - Link references are descriptive (e.g., "Configure an IAM Role and Permissions for Discovery Cloud," "Manage Users For Your Company").
Abbreviations: Flag - Several abbreviations lack first-use expansion: AWS (appears in title without expansion), IAM, HIPAA, and SQL. These should be spelled out on first use.
Overall WCAG Writing Score: Needs Attention
The content meets the target grade level of 12 or below, which is excellent for technical documentation. To improve readability further:
1. Break down compound technical instructions: Sentences like "If you do not see this SFTP Credentials section or are running into an error when attempting to generate credentials, reach out to your company's Admin to have them update your user permissions" contain multiple clauses and conditions. Split this into two sentences: "If you do not see this SFTP Credentials section, reach out to your company's Admin. Do the same if you run into an error when generating credentials."
2. Simplify time-related explanations: The sentence "If you have selected the Full Refresh update type, expect 5 - 6 hours for ingestion to kick in as the full refresh window is 6 hours" uses informal phrasing ("kick in") mixed with technical concepts. Revise to: "If you have selected the Full Refresh update type, ingestion will begin within 5-6 hours. The full refresh window is 6 hours."
3. Reduce prepositional phrase chains: "Place the file(s) from your environment to the correct SFTP directory" can be simplified to "Copy your file(s) to the correct SFTP directory" to reduce cognitive load and word count.
Plain Language: Needs Attention - Phrases like "ingestion to kick in" and "prohibited" could be simplified to "ingestion will start" and "not allowed." The term "flat" in "Files must be flat" is unexplained technical jargon.
Sentence Length: Pass - Most sentences are well under 25 words. The average of 15.6 words per sentence is excellent for accessibility.
Jargon: Needs Attention - Several technical terms lack explanation: "SFTP," "Switchboard," "partitioned files," "flat files," "Full Refresh update type," "ingestion," and "parquet." While SFTP is explained in the "SFTP 101 section below" reference, that section is not included in the article text provided.
Active Voice: Pass - The article predominantly uses active voice with clear imperative commands ("Click Get Switchboard," "Scroll to," "Ensure that you enter").
Heading Clarity: Good - Headings are action-oriented and descriptive ("Connect to Datavant's SFTP," "Monitor Data Onboarding," "Place File(s) in the Specified SFTP directory").
Link Text: Needs Attention - "SFTP 101 section below" is directional rather than descriptive. Better: "Learn about SFTP clients" or "SFTP client basics."
Abbreviations: Needs Attention - "SFTP" (Secure File Transfer Protocol), "GB" (gigabytes), "TB" (terabytes), "csv" (comma-separated values) are not spelled out on first use. While common in technical contexts, WCAG recommends defining abbreviations.
Overall WCAG Writing Score: Needs Attention
The content meets the readability target of Grade 12 or below. Here are three specific suggestions to improve it further:
1. Break down the compound sentence about user registration: The sentence "To enable SSO with Datavant's Connect platform, all users must first be registered with the portal using the same email address that is registered with your IdP" contains multiple clauses. Consider splitting it: "To enable SSO with Datavant's Connect platform, all users must first be registered with the portal. They must use the same email address that is registered with your IdP."
2. Simplify the off-boarding explanation: The sentence "Similarly, users off-boarded in your IdP won't be able to log in but their Datavant account needs to be deleted separately" could be clearer as two sentences: "Similarly, users off-boarded in your IdP won't be able to log in. Their Datavant account needs to be deleted separately."
3. Clarify the opening sentence structure: "Datavant currently supports integrating with your company's identity provider (IdP) to provide Single Sign On (SSO) login to Datavant's portal" could be more direct: "Datavant supports Single Sign On (SSO) through your company's identity provider (IdP)."
Plain Language: Needs Attention - Some technical phrases could be simplified. "SAML XML metadata document" and "SAML assertion encryption" are used without explanation. The phrase "IdP-initiated SSO" is technical jargon that may not be clear to all readers.
Sentence Length: Pass - Most sentences are under 25 words. The longest sentence is approximately 23 words, which is acceptable.
Jargon: Needs Attention - Multiple unexplained technical terms:
- "SAML 2.0 standard" (no explanation of what SAML is)
- "JIT (just-in-time) provisioning" (abbreviation explained but concept not defined)
- "IdP-initiated SSO" (technical term without context)
- "SAML assertion encryption" (no explanation)
- "SAML XML metadata document" (technical format not explained)
Abbreviations: Needs Attention:
- "IdP" - defined on first use ✓
- "SSO" - defined on first use ✓
- "JIT" - defined in parentheses ✓
- "IDP" - inconsistent capitalization (appears as both "IdP" and "IDP")
Active Voice: Pass - Most sentences use active voice effectively. One passive construction found: "users must first be registered with the portal" - could be "you must first register users with the portal."
Heading Clarity: Pass - "How to Request for SSO" is clear and action-oriented (minor note: could be "How to Request SSO" without "for").
Link Text: Cannot assess - No link text appears in the cleaned prose text (email address present but context unclear).
Overall WCAG Writing Score: Needs Attention
The content already meets the readability target of Grade 12 or below, which is excellent for technical documentation. To improve it further:
1. Break down compound technical sentences: The sentence "Copy and paste this text and replace the bracketed {BUCKET_NAME} and {BUCKET_PATH} in both instances under 'Resource'" contains multiple instructions in one sentence. Split this into: "Copy and paste this text. Then replace the bracketed {BUCKET_NAME} and {BUCKET_PATH} in both instances under 'Resource'."
2. Simplify the trust policy introduction: "Create an IAM role in your AWS account into which Datavant can assume" uses complex prepositional phrasing. Revise to: "Create an IAM role in your AWS account. Datavant will assume this role."
3. Clarify the cloud targets sentence: "For Cloud targets like Snowflake, Azure, Databricks, or GCP: Customers are responsible for building the ingest pipeline on their side once the data lands in S3" could be simplified to: "For cloud targets (Snowflake, Azure, Databricks, or GCP): You must build the ingest pipeline after data lands in S3."
Plain Language: Needs Attention - Some phrases could be simpler. "IAM role in your AWS account into which Datavant can assume" uses unnecessarily complex structure. "Populate the bucket name and path" could be "Enter the bucket name and path."
Sentence Length: Pass - All sentences are under 25 words. The average of 12.4 words per sentence is excellent for readability.
Jargon: Needs Attention - Several technical terms lack explanation:
- IAM Role (first use should explain: Identity and Access Management)
- Trust policy
- Permissions policy
- ARN (should spell out: Amazon Resource Name)
- Prefix (used without clear context for non-AWS users)
- Ingest pipeline
Abbreviations: Needs Attention
- AWS (explained as "Amazon Web Services" on first use would help)
- S3 (should be "Amazon S3" or "S3 storage" for clarity)
- IAM (never expanded)
- ARN (never expanded)
- GCP (never expanded as "Google Cloud Platform")
Active Voice: Pass - Most content uses active voice effectively ("Create an IAM role," "Copy and paste this text," "Provide these details").
Heading Clarity: Good - Step-by-step headings are clear and action-oriented. The "Overview" section properly sets context.
Link Text: Pass - The link "Understanding Distributions" is descriptive and meaningful. Email addresses are appropriately formatted.
Overall WCAG Writing Score: Needs Attention
The article has good structure and sentence length, but would benefit from expanding abbreviations on first use and providing brief explanations for technical terms that may be unfamiliar to users new to AWS or cloud storage concepts.
The content meets the readability target and is appropriate for a technical audience. To improve it further:
1. Break down multi-clause sentences: The opening sentence contains 32 words with multiple clauses: "This solution enables pre-sales feasibility and evaluation of datasets via the Datavant Connect Web Platform while the data remains in each source's respective AWS environment." Consider splitting this into two sentences: "This solution enables pre-sales feasibility and evaluation of datasets via the Datavant Connect Web Platform. The data remains in each source's respective AWS environment."
2. Simplify technical phrases: Replace complex constructions like "The defined policies are what is necessary for connecting" with "These policies are necessary to connect" to reduce unnecessary words and improve directness.
3. Use simpler vocabulary alternatives: Replace "respective" with "own," "subsequent" with "later," and "custo[mer]" (if complete) statements with more direct phrasing to maintain the accessible tone throughout.
Plain Language: Needs Attention - Some phrases are unnecessarily complex. "The defined policies are what is necessary" could be "These policies are necessary." The phrase "fees may be associated with this deployment" could be "this deployment may have fees."
Sentence Length: Flagged - One sentence exceeds 25 words:
- "This solution enables pre-sales feasibility and evaluation of datasets via the Datavant Connect Web Platform while the data remains in each source's respective AWS environment." (28 words)
Jargon: Needs Attention - Several technical terms lack explanation for non-AWS users:
- "IAM role" (explained contextually but no definition)
- "IaC" (Infrastructure as Code - abbreviation used without first defining)
- "AWS tenant" (not explained)
- "MFA" (Multi-Factor Authentication - not explained)
- "inline policy" (not explained)
- "cleanroom operations" (not explained)
Active Voice: Pass - Most content uses active voice effectively ("you will create," "navigate to," "click Create Role"). Minimal passive construction found.
Heading Clarity: Pass - Headings are clear, descriptive, and follow a logical numbered sequence (Step 1, Step 2, etc.). Subheadings like "Navigate to Create Role" provide clear action-oriented guidance.
Link Text: Cannot Assess - The cleaned prose text does not show link text formatting, but the reference to "AWS's Documentation" appears to be a link that should be more specific (e.g., "AWS IAM troubleshooting documentation").
Abbreviations: Flagged - Multiple abbreviations lack first-use definitions:
- "IAM" (Identity and Access Management)
- "AWS" (Amazon Web Services - assumed knowledge)
- "IaC" (Infrastructure as Code)
- "MFA" (Multi-Factor Authentication)
- "CLI" (Command Line Interface)
Overall WCAG Writing Score: Needs Attention
The content meets the readability target and is appropriate for the technical audience. Here are three specific suggestions to improve it further:
1. Break up compound sentences with multiple clauses. For example: "In this process, customers can provision an AWS IAM User within the customer's AWS account, and provide Datavant the AWS Account ID in the Datavant Connect platform" could be split into: "First, customers provision an AWS IAM User within their AWS account. Then, they provide Datavant the AWS Account ID in the Datavant Connect platform."
2. Simplify technical explanations. The sentence "Datavant only supports AWS IAM Roles owned by Datavant, and 'assumed' by a customer through a customer's AWS IAM User" could be rewritten as: "Datavant only supports AWS IAM Roles that Datavant owns. Customers access these roles through their AWS IAM User."
3. Use more concrete action verbs. Replace passive constructions like "S3 IAM roles have default permissions to make any action" with active phrasing: "S3 IAM roles can perform any action within your customer path by default."
Plain Language: Needs Attention - Several complex technical phrases could be simplified: "provision an AWS IAM User," "assume (an AWS IAM operation) into the IAM role," and "implement credentials" use unnecessarily formal language.
Sentence Length: Pass - Most sentences are well under 25 words. The average of 15.3 words per sentence is excellent for readability.
Jargon: Needs Attention - Multiple technical terms lack explanation:
- IAM (defined only as "AWS IAM")
- ARN (mentioned as "Role ARN" with no definition)
- Lambda function (mentioned without context)
- CLI and API (used without expansion)
Abbreviations: Needs Attention - Several abbreviations are not expanded on first use:
- S3 (never defined)
- AWS (never defined, though commonly known)
- ARN (never defined)
- CLI (never defined)
- API (never defined)
Active Voice: Needs Attention - Multiple passive constructions found:
- "can be used to assume"
- "would then be used to assume"
- "is set"
- "are generated"
Heading Clarity: Good - Headings like "Overview," "Generate an S3 IAM Role," and "Option #1" / "Option #2" are clear and descriptive.
Link Text: Cannot assess - The cleaned prose text shows a reference to "Read more about using External IDs here" but link implementation cannot be evaluated from this format.
Overall WCAG Writing Score: Needs Attention
The content successfully meets the target readability level. Here are three specific suggestions to improve it further:
1. Break down compound instructions: The sentence "If your partner ran the Overlap report using tables you shared, you cannot create a token export" combines a conditional clause with a restriction. Consider splitting this: "Your partner may run Overlap reports using tables you shared. In these cases, you cannot create a token export."
2. Simplify technical phrases: The phrase "tokens encrypted with the
3. Reduce prepositional phrase chains: "Follow the instructions in the How to Pick Up Distributed Data article to access this environment and retrieve files using SFTP or an S3 Transfer" stacks multiple prepositional phrases. Break into two sentences: "Follow the instructions in the How to Pick Up Distributed Data article. This will help you access the environment and retrieve files using SFTP or S3 Transfer."
Plain Language: Needs Attention - Some unnecessarily complex phrases found: "securely download token exports from the Datavant Connect platform" could be "download token exports securely from Datavant Connect"; "analyses that can't be done in Assess" could specify what types of analyses.
Sentence Length: Pass - All sentences are well under 25 words. The longest sentence is approximately 20 words, which is excellent for accessibility.
Jargon: Needs Attention - Several technical terms lack explanation:
- "SFTP" (not defined)
- "S3 Transfer" (not defined)
- "S3 directory" (not explained)
- "site-specific encryption key" (assumed knowledge)
- "transit encryption key" (not distinguished from site-specific key)
Active Voice: Pass - Article predominantly uses active voice. One passive construction found: "Token Exports are stored in an S3 directory" - could be "Datavant stores Token Exports in an S3 directory," though passive voice is acceptable here.
Heading Clarity: Pass - Headings are clear, descriptive, and follow a logical task-based structure (What/How/Step-by-step format).
Link Text: Pass - Link text is descriptive ("Share a Table or Segment article," "How to Pick Up Distributed Data article," "Use Datavant Desktop").
Abbreviations: Needs Attention - Several unexplained abbreviations:
- "SFTP" (should be "SFTP (Secure File Transfer Protocol)" on first use)
- "S3" (should be "S3 (Simple Storage Service)" on first use)
- "AWS" (should be "AWS (Amazon Web Services)" on first use)
- "CLI" (should be "CLI (Command Line Interface)" on first use)
- "OS" (should be "OS (Operating System)" on first use)
- "ECS, EKS, EC2" (all unexplained)
Overall WCAG Writing Score: Needs Attention
The article has strong structure and sentence length control, but requires better support for technical terms and abbreviations to meet full WCAG 2.2 accessibility standards.
1. Break down long compound sentences: While the average sentence length is good at 13.6 words, some sentences pack multiple concepts together. For example, "The data processing status for a Table reflects the aggregate status of all its file(s). If a Table contains multiple files, the status of the Table will show the most critical file level status, e.g. 'Failed,' 'Requires Review,' or 'Pending Window End.'" could be simplified by reducing the repetition of "status" and using simpler phrasing like "When a table has multiple files, it displays the most urgent file status."
2. Replace technical terminology with simpler alternatives where possible: Terms like "aggregate status," "onboarding data checks," and "5-hour rolling window" could be explained more plainly. For instance, "aggregate status" could be "combined status" or "overall status," which uses more common vocabulary.
3. Simplify the status workflow descriptions: The sequences "Not Loaded → In Queue → Validating → Failed / Requires Review → Ingesting → Pending Window End → Success" are comprehensive but could benefit from a brief lead-in sentence using simpler language, such as "Your file moves through these steps:" to reduce cognitive load before presenting the technical progression.
Plain Language: Needs Attention - Some terms are unnecessarily complex: "aggregate status" (use "overall status"), "queued them for ingestion" (use "lined them up for upload"), "onboarding data checks" (explain what checks are performed).
Sentence Length: Pass - Average sentence length is 13.6 words, well below the 25-word threshold. Most sentences are appropriately concise.
Jargon: Needs Attention - Several unexplained technical terms:
- "S3 or SFTP directory" (not explained for non-technical users)
- "5-hour rolling window" (not explained why or what happens)
- "Incremental Update Type" vs "Full Refresh Update Type" (briefly mentioned but not defined)
- "onboarding data checks" (not explained what is being checked)
Active Voice: Pass - Most sentences use active voice effectively: "navigate to the My Data page," "select the relevant Table," "ensure that the file headers match."
Heading Clarity: Good - Headings are action-oriented and clear: "Monitor Table Upload Status," "Investigate Table Upload Failures," "Resolve the Requires Review Status."
Link Text: Needs Attention - Contains vague link text: "accessing it here" should be more descriptive, such as "access the table troubleshooting demo video."
Abbreviations: Needs Attention - "S3" and "SFTP" are not explained on first use. These should be written out or briefly explained, e.g., "S3 (Amazon cloud storage)" or "SFTP (secure file transfer)."
Overall WCAG Writing Score: Needs Attention
The content successfully meets the readability target and is generally clear. Here are three specific suggestions to improve it further:
1. Simplify compound technical phrases: Change "CLI deployment methods" to "CLI deployments" and "Datavant tokenization software" to "the tokenization software" on subsequent mentions to reduce cognitive load and syllable count.
2. Break down the credential explanation: The opening sentence "They serve as a password, authenticating that the user has permission to run the software with a specific encryption key" could be simplified to two shorter sentences: "They work like a password. They confirm you have permission to use the software with a specific encryption key."
3. Reduce technical density: The phrase "provision credential access" and "provision application credentials to a user" uses the formal term "provision" twice. Replace with the simpler "grant credential access" and "give application credentials to a user" to lower the reading level while maintaining clarity.
Plain Language: Needs Attention - Most language is clear, but "provision credential access" is unnecessarily formal. "Grant access" or "give access" would be plainer alternatives.
Sentence Length: Pass - All sentences are well under 25 words. The longest sentence contains approximately 21 words ("They serve as a password, authenticating that the user has permission to run the software with a specific encryption key").
Jargon: Needs Attention - Several technical terms lack explanation:
- "CLI" (appears multiple times, never defined)
- "encryption key" (used without context for non-technical users)
- "Site Admin" (relationship to regular admin unclear)
- "tokenization software" (unexplained technical term)
Active Voice: Pass - The article predominantly uses active voice with clear imperative instructions ("go to," "select," "click," "contact").
Heading Clarity: Pass - Headings are descriptive and action-oriented ("How to generate CLI credentials" and "Ensure credential permissions are enabled" clearly indicate content).
Link Text: Pass - The email address "support@datavant.com" is appropriately specific. No vague "click here" links present.
Abbreviations: Needs Attention - "CLI" is never expanded or explained despite being central to the article's purpose.
Overall WCAG Writing Score: Needs Attention
The content meets the target reading level, but can be improved further with these specific changes:
1. Break down complex compound sentences: The sentence "If you require support for a v3 version after this date, we will require you to upgrade to the latest v4 version first" contains multiple clauses. Simplify to: "If you require support for a v3 version after this date, you must upgrade first. We only support v4 versions."
2. Simplify technical explanations: The phrase "v4.1.0 introduced prefix and suffix stripping for first and last names as a pre-processing step for all tokens built off of first and last name PII elements" is dense with technical concepts. Break into shorter sentences: "v4.1.0 processes names differently. It removes prefixes and suffixes from first and last names. This happens before creating tokens from name data."
3. Use simpler vocabulary where possible: Replace "discontinue support" with "stop supporting" and "outbound firewall connections" with "outbound connections (firewall rules)" to maintain technical accuracy while being more direct.
Plain Language: Needs Attention - Some phrases are unnecessarily complex: "on-premise applications will no longer work and attempts to run a prior version will result in an error" could be "on-premise applications will stop working. You will get an error if you try to run older versions."
Sentence Length: Pass - Most sentences are concise. One borderline example at 24 words: "v4.1.0 introduced prefix and suffix stripping for first and last names as a pre-processing step for all tokens built off of first and last name PII elements."
Jargon: Needs Attention - Several unexplained technical terms:
- "on-premise applications" (not defined for general audience)
- "command line executables"
- "command line argument"
- "PII elements" (acronym explained later but not at first use)
- "prefix and suffix stripping"
- "outbound firewall connections"
Active Voice: Pass - Primarily uses active voice. One passive construction: "the version is listed in the top right corner" could be "you'll see the version in the top right corner."
Heading Clarity: Good - Questions are clear and user-focused (e.g., "How do I know if I am using v3?" and "What happens if I don't upgrade?")
Link Text: Needs Attention - Contains vague link references: "This article provides all Technical Requirements" and "Steps 1-4 in our Quick Start Guide" - the actual link text is not visible in the prose, but ensure links describe the destination clearly.
Abbreviations: Needs Attention -
- "v3" and "v4" (version abbreviations, acceptable in context)
- "PII" (used without initial expansion)
- "CLI" (in title, not explained in body text)
- "DeID" (product name, acceptable)
Overall WCAG Writing Score: Needs Attention
The content meets the target grade level effectively. To improve readability further:
1. Break down multi-clause sentences: While average sentence length is good at 13.2 words, some sentences contain multiple instructions in one. For example, "From the Download page in Connect, go to the S3 Credentials section and create a new IAM Role" could become two sentences: "From the Download page in Connect, go to the S3 Credentials section. Create a new IAM Role."
2. Simplify technical phrases: Replace phrases like "integrating a Datavant-owned IAM Role to a customer Databricks account" with "connecting a Datavant IAM Role to your Databricks account." Use "connecting" instead of "integrating" and "your" instead of "a customer's" for directness.
3. Reduce syllable-heavy words: The phrase "Copy the Role ARN that is generated in this step" could become "Copy the Role ARN created in this step" (replacing "generated" with "created" saves a syllable and maintains clarity).
Plain Language: Needs Attention - Several instances of complex phrasing exist: "There is no risk of writing data to the wrong S3 prefix, as Datavant manages the IAM Role" could be simplified to "Datavant manages the IAM Role to prevent data from going to the wrong location."
Sentence Length: Pass - Most sentences are concise. One borderline example: "This works by integrating a Datavant-owned IAM Role to a customer Databricks account so Databricks can write directly to the Datavant S3 bucket" (24 words - acceptable but could be split).
Jargon: Needs Attention - Several unexplained technical terms:
- IAM Role (first mention needs expansion)
- S3 bucket/prefix
- ARN
- External ID
- External Location
- Schema
- Catalog
Abbreviations: Needs Attention - Unexplained abbreviations found:
- IAM (never spelled out)
- ARN (never spelled out)
- S3 (never spelled out)
- AWS (never spelled out)
- ID (used extensively without expansion)
Active Voice: Pass - Strong use of active voice and imperative commands throughout ("Create," "Select," "Copy," "Enter").
Heading Clarity: Good - Step numbers are clear and descriptive (e.g., "Step 1. Create an IAM Role").
Link Text: Cannot assess - No link text present in cleaned prose version.
Overall WCAG Writing Score: Needs Attention
The content meets the readability target and is accessible to most readers. Here are three specific suggestions to improve it further:
1. Break up the credential noting instruction: The sentence "Note your username, password, SFTP hostname, and port number" could be converted to a bulleted list to make the four required items more scannable and easier to follow during the actual task.
2. Simplify the permissions error sentence: The sentence "If you do not see this SFTP Credentials section or are running into an error when attempting to generate credentials, reach out to your company's admin to have them update your user permissions" is complex with multiple clauses. Break it into two sentences: "If you do not see this SFTP Credentials section, reach out to your company's admin. They can update your user permissions."
3. Add brief context for "toggled on": The phrase "You will need Application Download and Discovery Pages toggled on" uses the technical term "toggled" without explanation. Consider "You will need Application Download and Discovery Pages turned on" for clearer meaning.
Plain Language: Needs Attention - Terms like "SFTP," "Switchboard SFTP site," "command-line SFTP," and "toggled on" appear without explanation for users unfamiliar with these concepts.
Sentence Length: Pass - All sentences are under 25 words. The longest is 24 words ("If you do not see this SFTP Credentials section or are running into an error when attempting to generate credentials, reach out to your company's admin to have them update your user permissions").
Jargon: Needs Attention - Unexplained technical terms include: "SFTP" (appears multiple times without definition), "Switchboard," "SFTP client," "command-line SFTP," "port number," and "toggled."
Active Voice: Pass - Instructions use predominantly active voice with clear imperative statements (e.g., "go to," "scroll," "click," "note").
Heading Clarity: Pass - The title clearly describes the task users will accomplish.
Link Text: Not Applicable - No link text present in the provided prose content.
Abbreviations: Needs Attention - "SFTP" is used throughout without being spelled out as "Secure File Transfer Protocol" on first use. "e.g." appears but is acceptable in technical documentation.
Overall WCAG Writing Score: Needs Attention
The content meets the readability target effectively. To improve it further:
1. Break down the compound sentence about v5.1 deprecation - The sentence "Customers adopting CLI v5.0 should plan to upgrade when CLI v5.1 is available because all prior CLI versions (including v5.0) will be deprecated one year after the release of v5.1" contains multiple clauses. Consider splitting it: "Customers adopting CLI v5.0 should plan to upgrade when CLI v5.1 is available. All prior CLI versions (including v5.0) will be deprecated one year after v5.1 releases."
2. Simplify the phrase "coordinated through Technical Solutions, who coordinate access" - This creates redundancy with "coordinate" appearing twice. Revise to: "Technical Solutions manages access to the approved build and supports onboarding."
3. Define "deprecated" for non-technical readers - While the score is good, adding a brief clarification would help: "deprecated (no longer supported)" to ensure all readers understand this critical term.
Plain Language: Needs Attention - "deprecated" and "limited release" appear without explanation. Consider defining or replacing with simpler alternatives.
Sentence Length: Pass - All sentences are under 25 words, with the longest at approximately 24 words.
Jargon: Needs Attention - "CLI" (explained as context), "deprecated" (unexplained), "limited release" (unexplained), "long-term supported version" (unexplained), and "onboarding" could benefit from brief definitions.
Active Voice: Pass - Content primarily uses active voice effectively ("Run the -v command," "reach out to your Datavant point").
Heading Clarity: Pass - Questions are clear and user-focused, following FAQ best practices.
Link Text: Pass - Email address "support@datavant.com" is descriptive and actionable.
Abbreviations: Needs Attention - "CLI" appears extensively but is never expanded on first use. "FAQ" in title is also unexpanded.
Overall WCAG Writing Score: Needs Attention
The content successfully meets the readability target of Grade 12 or below. To improve it further:
1. Break down compound technical phrases: Phrases like "pre-sales feasibility and evaluation of datasets via the Datavant Connect Web Platform while the data remains in each source's respective AWS environment" contain multiple concepts. Consider: "This solution enables pre-sales feasibility checks. You can evaluate datasets through the Datavant Connect Web Platform. The data stays in each source's AWS environment."
2. Simplify conditional instructions: The sentence "When selecting an S3 path, if you want to select the directory, select the radio button next to the name. If you want to select a sub-directory within the path, select the name of the path" could be clearer with a bulleted list format showing the two distinct actions.
3. Add brief definitions for AWS terminology on first use: Terms like "Glue Database," "Glue Tables," and "Glue Crawlers" appear without context. Consider adding a one-sentence explanation when first introduced, such as: "Glue Database (a metadata catalog in AWS)."
Plain Language: Needs Attention - The opening sentence contains 32 words with multiple embedded clauses. "This solution enables pre-sales feasibility and evaluation of datasets via the Datavant Connect Web Platform while the data remains in each source's respective AWS environment" should be broken into shorter sentences.
Sentence Length: Flag - One sentence exceeds 25 words: "This solution enables pre-sales feasibility and evaluation of datasets via the Datavant Connect Web Platform while the data remains in each source's respective AWS environment" (32 words).
Jargon: Needs Attention - Several technical terms lack explanation: "Glue Database," "Glue Tables," "Glue Crawlers," "Data Catalog," "Schemas," "S3 directories," "sub-directories," and "AWSGlueServiceRole policy."
Active Voice: Pass - Most instructions use clear active voice ("you will create," "click Databases," "Enter a name").
Heading Clarity: Pass - Step-by-step headings are clear and descriptive (e.g., "Step 0: Create a Glue Database," "Step 1: Create a Glue Crawler").
Link Text: Pass - Reference to "AWS Documentation" is appropriately descriptive.
Abbreviations: Needs Attention - "AWS" and "S3" appear without first defining them (Amazon Web Services, Simple Storage Service).
Overall WCAG Writing Score: Needs Attention
The content meets the readability target successfully. To improve it further:
1. Break up compound instructions: Several sentences combine multiple actions. For example, "Check that your credentials are valid for the site and rerun the application" could be split into two sentences: "Check that your credentials are valid for the site. Then rerun the application." This appears multiple times throughout the article.
2. Simplify nested information: The phrase "These credentials are not valid to access the connect key from {source_site_name} to {destination_site_name}" contains multiple prepositional phrases. Consider: "These credentials cannot access the connect key. The key connects {source_site_name} to {destination_site_name}."
3. Add brief explanations for technical paths: Instructions like "Access the Settings > User Management > User tab" assume knowledge of navigation. Consider adding: "Access the Settings > User Management > User tab (found in the main menu)" to provide context.
Plain Language: Needs Attention - Several instances of technical jargon without context, such as "connect key," "transit keys," "PII fill rates," and "token success rate" appear without explanation for users who may be unfamiliar with these terms.
Sentence Length: Pass - Most sentences are concise and well under 25 words, contributing to the strong readability score.
Jargon: Needs Attention - Unexplained technical terms include:
- "PII fill rates"
- "token success rate"
- "connect key" and "transit keys"
- "reference data" (used frequently without definition)
- "configuration" (context-specific meaning not explained)
Active Voice: Pass - Most instructions use active voice effectively ("Check that your credentials," "Confirm that," "Access the Download tab").
Heading Clarity: Needs Attention - "Category A Error Codes" lacks context. What makes these "Category A"? Are there other categories? The heading "Structured log files include" is incomplete as a standalone heading.
Link Text: Needs Attention - "Access the Download tab" and "Access the Configurations tab" appear to reference clickable elements but context suggests these may be directions rather than hyperlinks. If these are links, they should be formatted clearly.
Abbreviations: Needs Attention - "PII" appears without expansion on first use. "CLI" appears in the title but is not expanded in the body text.
Overall WCAG Writing Score: Needs Attention
The content meets the readability target and is appropriately clear for technical documentation. Here are three specific suggestions to improve it further:
1. Simplify compound sentences with multiple clauses. For example, "As the number of projects grows, it becomes harder to keep track of important details—such as which partners have collaborated and on what activities" could be split into two sentences: "As the number of projects grows, tracking becomes harder. You may lose sight of which partners collaborated and what activities they completed."
2. Break down the dense instruction in the "Create a new project" section. The phrase "The project start date. This can be in the past, for existing projects, or in the future, for planned projects" contains multiple concepts. Consider: "The project start date. You can use a past date for existing projects. You can use a future date for planned projects."
3. Reduce prepositional phrase chains. The sentence "By keeping all project details in one place, teams can work more efficiently, complete projects faster, maintain accurate records, and collaborate more effectively with colleagues and partners" stacks many actions together. Consider breaking this into a bulleted list under "By keeping all project details in one place, teams can:"
FK RECOMMENDATIONS:
Plain Language: Pass - The article uses clear, straightforward language appropriate for the audience. Terms like "centralized view" and "seamlessly" are common enough to not impede understanding.
Sentence Length: Pass - Most sentences are well under 25 words. The longest sentence is approximately 32 words: "By keeping all project details in one place, teams can work more efficiently, complete projects faster, maintain accurate records, and collaborate more effectively with colleagues and partners." Consider breaking this into a list format.
Jargon: Pass - Technical terms like "encryption key," "portal," and "project permissions" are appropriate for the target audience using a data connectivity platform and are explained through context.
Active Voice: Pass - The article predominantly uses active voice with clear instructions ("Click Create Project," "Enter the following information," "Select Create Project").
Heading Clarity: Pass - Headings are descriptive and action-oriented ("Why use the Project Dashboard," "Create a new project," "Add and archive partners").
Link Text: Needs Attention - The article text appears truncated at "or already wo" making it impossible to assess all link text. Ensure any links use descriptive text rather than "click here" or URLs.
Abbreviations: Pass - No unexplained abbreviations are present in the provided text.
Overall WCAG Writing Score: Good
The content meets the readability target successfully. To improve it further:
1. Add brief context sentences to code examples: Phrases like "%Y/%m/%d, %m/%d/%Y, %Y%m%d, %m%d%Y, %Y-%m-%d, and %m-%d-%Y" are presented as pure data without transition sentences. Consider: "The system accepts six date formats, including: %Y/%m/%d, %m/%d/%Y..." to help readers process the information more easily.
2. Break up the medical code section: The rapid succession of data types (ICD, NPI, DRG, LOINC, CPT/HCPCS, NDC) at the end could be reorganized with a sentence like "The following medical and healthcare coding systems are supported:" to provide cognitive structure.
3. Expand the administrative gender example: "M, Female, f, female" could benefit from a clarifying phrase such as "The system recognizes various gender formats, including abbreviated and full-length entries like: M, Female, f, female" to make the pattern more explicit.
Plain Language: Pass - The article uses clear, straightforward language appropriate for the audience. Technical terms are necessary and properly contextualized.
Sentence Length: Pass - All sentences are well under 25 words. The longest sentence is approximately 22 words ("The validation rules for each field must be met in order for a token that uses that field to be successfully generated").
Jargon: Needs Attention - Several unexplained technical terms:
- "tokenization" (used without definition in article text)
- "re-identification" (specialized privacy term)
- "ICD diagnosis codes" (unexplained medical acronym)
- "NPI numbers" (unexplained healthcare acronym)
- "DRG codes" (unexplained medical acronym)
- "LOINC codes" (unexplained medical acronym)
- "CPT/HCPCS codes" (unexplained medical acronyms)
- "NDC" (unexplained pharmaceutical acronym)
Active Voice: Pass - The article predominantly uses active voice ("Use this data type if...", "Mapping your input fields will determine..."). Minimal passive constructions are appropriate where used.
Heading Clarity: Needs Attention - The cleaned text appears to lack clear headings for each data type. Consider adding descriptive subheadings like "Name Data Types," "Address Data Types," and "Medical Code Data Types" to improve scanability.
Link Text: Pass - References like "What is a Configuration?" and "Data Hygiene Best Practices" provide clear, descriptive link text that indicates destination content.
Abbreviations: Needs Significant Work - Multiple unexplained abbreviations:
- US (used throughout, assume United States)
- ICD (no expansion provided)
- NPI (no expansion provided)
- DRG (no expansion provided)
- LOINC (no expansion provided)
- CPT (no expansion provided)
- HCPCS (no expansion provided)
- NDC (expansion cut off: "National Dru...")
Overall WCAG Writing Score: Needs Attention
The article has strong fundamentals (sentence length, active voice, plain language) but would benefit from expanding abbreviations on first use and providing brief definitions for specialized medical/healthcare coding systems to meet WCAG 3.1.3 (Unusual Words) and 3.1.4 (Abbreviations) guidelines.
The content already meets the readability target well below Grade 12. Here are three specific suggestions to improve it further:
1. Complete truncated sentences in the Error Code List: Several entries are incomplete or awkwardly structured. For example, "F. First Name was missing was missing or unusable" contains a duplicate phrase, and "G. Administrative Gender was missing or unusable" appears to be missing entirely from the list despite being referenced in the example "XXX - LFGD00". Review and complete all list items for clarity.
2. Add a brief introductory sentence before the format explanation: The article jumps directly into "The format of an error token is as follows:" without completing the thought. Add a clear subject, such as "The format of an error token is as follows: XXX- followed by 6 characters..." to make the structure clearer.
3. Expand the "For more information" reference: The phrase "For more information, see Tokenization FAQs" appears after only one error code example. Consider specifying what type of additional information readers will find there, such as "For troubleshooting steps, see Tokenization FAQs" to set clearer expectations.
Plain Language: Needs Attention - The term "token transformation" and "encryption key" appear without explanation. While "error token" is explained through context and examples, these technical concepts need brief definitions for non-technical users.
Sentence Length: Pass - All sentences are well under 25 words. The average of 8.8 words per sentence is excellent for accessibility.
Jargon: Needs Attention - Several technical terms lack explanation:
- "Token transformation" (used in error T)
- "Encryption key" (mentioned in error T description)
- "Custom Field" (referenced in error C)
- "Administrative Gender" (referenced but not listed in the code list)
Active Voice: Pass - The article primarily uses active and direct constructions. Passive voice instances like "are designed," "are filled," and "may be generated" are acceptable and don't impede clarity.
Heading Clarity: Needs Attention - The article appears to have only "Error Code Overview" as a heading. Adding clear subheadings would improve navigation, such as "Error Token Format," "Error Code Examples," and "Error Code List."
Link Text: Needs Attention - "Tokenization FAQs" is reasonably descriptive, but appears in isolation. Ensure the full context is provided so users understand when to click this link.
Abbreviations: Needs Attention - Multiple abbreviations are undefined:
- "SSN" (likely Social Security Number, but should be spelled out on first use)
- "ZIP" (Zone Improvement Plan, though commonly understood)
- "FAQs" (Frequently Asked Questions, should be spelled out)
Overall WCAG Writing Score: Needs Attention