Renaming proposition

[kaligrafy]

Proposition for renaming classes, attributes and actions, plus users categories:

Naming conventions

Interview manipulation by use case:

• Validation: Live validation of interviews data, shown to respondent and interviewers during the interview
• Correction: Manual correction of interviews data, done by admin/correctors
• Audit: Automated validation of interviews data, done by the server and shown to admin/correctors

Users:

• Admin: Users with the admin role can administer the surveys, including monitoring and correcting interviews
• Corrector: Users with the correctors role can correct interviews data
• Participant: Users with the participant role can fill the surveys (also called Respondent)
• Interviewer: Users with the interviewer role can fill out interviews for a participant by phone, in person or remotely, or can assist participants with their interviews

Please discuss if you agree, and if not, propose better (If you don't like a name, propose a better one :-) )

[samuel-duhaime]

For the admin user, do we want to put some role, because right now admin is too broad of a type ?

[tahini]

For the admin user, do we want to put some role, because right now admin is too broad of a type ?

Yes we do, eventually, none of us should be admin, but we should all have permissions of some kind. We have all the framework for this and we have interviewer/validator roles, but we stopped there as it was enough at the time and didn't get time to work on it...

[tahini]

Sounds good for the renaming. But is that exhaustive enough? What about the case of somebody visualizing the audits (in the summary page) and just setting the interview as valid/invalid, complete/incomplete, questionable? This process does not require correction and we may not want all users who can do that to actually have the permission to correct the interview?

You think of OD surveys, but there are many others where we may just want to manually [in]validate them without giving right to edit.

[kaligrafy]

I think we can still do better renaming and separating users/permissions

[tahini]

Roles/permissions and renaming are 2 separate things anyway.

[kaligrafy]

New proposition:

Evolution Platform Nomenclature

Process Names

Interview Process

• interview
  Base process for all interview types

  a. respondentInterview
  - Process where a respondent completes their own interview
  - Real-time data collection from the respondent
  - Can be incomplete

  b. assistedInterview
  - Interview conducted by an interviewer (phone/chat/in-person)
  - Can be starting fresh or continuing a respondentInterview

• realTimeValidation (shorthand: validation)

  • Frontend/backend validation during interview
  • Data type checking
  • Response coherence verification
  • Applies to both interview types and to correction process (see below)

Post-Interview Processing

1. audit (process) & auditReport (group of results) & auditResult (single result) & auditCheck (single validation/check)

   • Automated backend process analyzing completed interviews
   • Generates auditResult instances (error, warning or info)

2. review (manual)

   • Evaluation of audit reports
   • Decision-making process on interview validity
   • Determination if corrections are needed
   • Interview acceptance or rejection

3. correction (manual)

   • Modification of interview data
   • Direct editing of interview responses
   • Data cleaning and improvement

4. enhancement (automated)

   • Enhancement of interview data
   • Data improvement and quality enhancement

Monitoring and export

• monitoring
  • Survey monitoring with widgets (plots of started/completed interviews by different variable)
  • Interviewers performance monitoring
• export
  • Data extraction of interviews with original responses (non reviewed/non corrected)
  • Data extraction of reviewed//corrected interviews

Role Names

• respondent

  • Individual providing interview responses
  • Primary data source
  • Self-guided interview participant

• interviewer

  • Phone, chat or in-person support personnel
  • Guides respondents through interview process
  • Real-time data collection specialist

• system-auditor (system role)

  • Automated system process
  • Performs systematic checks
  • Generates audit reports

• reviewer

  • Evaluates audit reports
  • Makes decisions on interview validity
  • Determines necessary actions, like corrections needed

• corrector

  • Implements required corrections
  • Adjusts geographic data
  • Modifies interview responses

• admin

  • Monitoring
  • Manages data exports
  • System administration
  • (To be replaced by specific permissions)

Role-Process Relationships

interview
    ├── respondentInterview (respondent)
    │   └── realTimeValidation
    └── assistedInterview (interviewer)
        └── realTimeValidation

system-auditor
    └── audit
        └── auditReport

reviewer
    └── review

corrector
    └── correction
        └── realTimeValidation

admin
    ├── monitoring
    └── export

Notes

• A single user may have multiple roles (e.g., reviewer and corrector)
• Admin role will be replaced by granular permissions
• Real-time validation applies to both interview types
• Audit is exclusively a system process, reviewing is the human review of audits and audit reports

[kaligrafy]

@tahini Waiting for your review :-)

[tahini]

@kaligrafy sounds good. I already used this proposition in the ISCTSC article!

[tahini]

For eventual PRs doing the renaming, please do one at a time to make it simpler to track, as each may impact many variable names and quite a burden to review ;-)

[kaligrafy]

Nomenclature updated in the code:

• Answer
• Response
• RespondentInterview
• AssistedInterview
• RealTimeValidation
• Audit
• AuditCheck
• AuditCheckResult
• AuditReport
• Review
• Correction
• Enhancement
• Monitoring
• Export
• Respondent
• Interviewer
• SystemAuditor
• Reviewer
• Corrector
• Admin