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

As our documentation evolves into this structure, this section will house deeper discussions on topics such as:

• We are all different: The philosophy of designing for a wide range of abilities and preferences, and how this shapes our approach to survey design.
• The Philosophy of Accessibility First: Why we prioritize formats like Easy Read and Sign Language directly in the data collection layer, rather than as an afterthought.
• Rooted in the Disability Movement: The historical and ethical foundations of our work, and how the principles of the disability rights movement inform our design choices.

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.

Content that helps you understand how to create high-quality surveys, including:

• Confidence Index: Understand how the platform identifies potential bot activity and low-effort submissions through behavioral analysis.
• How to choose the right question type
• Using Markdown: Why Accessible Surveys uses Markdown for rich text formatting and its benefits for accessibility.

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.

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.