Explanation
The Explanation section is understanding-oriented. While Tutorials take you by the hand and How-to Guides provide exact steps to solve a problem, Explanations zoom out to provide the big picture.
These articles are designed for study. They offer context, historical background, architectural reasons, and the "why" behind the design decisions of the Accessible Surveys platform.
Principles
- We Have Different Needs: Disability as an interaction between impairment and barriers, and why one survey needs several routes.
- Accessibility First: Why accessibility belongs in the data layer rather than in a final pass, and what that changes for respondents and analysis.
- Rooted in the Disability Movement: The history, the CRPD principles, participation, and the language the platform uses.
Application Architecture and Key Concepts
Topics that explain the underlying architecture of the platform, including:
- Understanding Survey, Form, Page, Section and Question Hierarchy: A detailed explanation of the hierarchical structure of surveys and how each level interacts with the others.
- How does the compose view work: An explanation of the compose view and how it allows users to build and organize survey content.
- The concept of Modes: Why we use modes to manage the complexity of survey configuration and how it helps users focus on specific tasks.
- Building and Versioning: An explanation of why it is necessary to compile a survey into a frozen snapshot before sharing it, and how strict version control protects data integrity during iterative design.
- Understanding Form Logic: A deeper dive into how the platform's logic engine evaluates mathematical expressions and ternary operators to create dynamic surveys.
- Test and Production Survey Links: Why we have separate links for testing and production surveys and what are the differences.
- The Role of Batches: Why temporal grouping is a fundamental architectural decision for longitudinal survey analysis and how its lifecycle works.
- Respondent accounts: How respondent accounts are managed and their role in the survey process.
- Resuming Incomplete Surveys: How state machine snapshots and browser-based authentication allow respondents to resume incomplete surveys across browser restarts and network changes.
Survey Quality
- Understanding Section Sharing & Reusability: How shared sections enable reusable accessibility assets (Sign Language, Easy Read, translations), longitudinal data comparability, and reduced survey fatigue via smart pre-fill.
- Understanding Randomization: How stable, seeded shuffling works to reduce order bias.
- Choosing a Form Layout for Cognitive Accessibility: The trade-offs between one question per page and multiple questions per page, and how layout interacts with accessible modes.
Content that helps you understand how to create high-quality surveys, including:
- Respondent Behavior & Data Quality: Conceptual background on satisficing theory, client-side paradata, response latency, and detecting low-effort or automated submissions.
- How to choose the right question type
- Using Markdown: Why Accessible Surveys uses Markdown for rich text formatting and its benefits for accessibility.
Accessible Formats and Production
- Producing Surveys in Plain Language or Easy Read: Best practices, standards, and production guidance for writing in Plain Language and producing Easy Read surveys in collaboration with persons with intellectual disabilities.
- Producing Surveys in Sign Languages: Studio recording standards, interpreter accreditation, dialect selection, and Deaf community review for sign language survey videos.
Data Privacy, Security and Ethics
- Authentication and Identity: An explanation of how authentication is implemented and managed across the platform.
- Authorization and Security Rules: An explanation of how Firebase Security Rules protect survey configurations and respondent data.
- Data Privacy and Security: The conceptual framework behind how we handle anonymized datasets, verified accounts, and data export responsibilities.
- GDPR Compliance and Survey Privacy: Practical guidance for survey creators on controller/processor roles, lawful basis, sensitive data, data subject rights, and international data transfers.
- Writing a Survey Privacy Policy: How to draft a clear, plain-language, GDPR-compliant privacy notice for your surveys.
Useful web-related or technical concepts
- What is JSON?: Why we use the JSON data format for structural exports and localization, instead of tabular formats like CSV.
- Understanding CSS Units: An explanation of the different CSS units available for styling tokens and how they affect responsive design and accessibility.
- Understanding CSS Variables: How the survey engine uses CSS custom properties and scaling tokens for dynamic theming and accessibility modes.