Tracker for friction when consulting documentation

[TSSlade]

This'll be a running list of efforts to consult documentation and friction encountered along the way. Intended for use as a resource as we edit, reorganize, otherwise improve our docs.

Posts will generally follow a structure something like this:

• Intent:
• Effort:
• Result:
• Suggestion (if any):

[TSSlade]

• Intent: Find out how to integrate a new font/typeface into a group
• Launch docs.tangerinecentral.org
  • Effort: Search font
  • Result: Hits for changelogs 3.4.0 and 3.8.1
  • Effort: Search typeface
  • Result: No results

Suggestion (if any): Include a section on how to customize the font to be used in your instruments.

[TSSlade]

• Intent: Reset password for user

• Launch docs.tangerinecentral.org

  • Effort: Search for password
  • Result: Returned results below:

• Suggestion (if any): Entry describing that

  • password recovery became available as of Tangerine v3.x
  • prior to v3.x, deletion and recreation of the user by RTI helpdesk is the only recourse
  • on v3.x+, a server's admin user can reset the user password via the Users > Actions > Edit interface

[TSSlade]

• Intent: Respond to user helpdesk query about accessing results on the tablet that have not yet been uploaded

• Launch docs.tangerinecentral.org

  • Effort: Search for upload
  • Result: Returned hits for Data Synchronization page
  • Suggestion:
    • Improve documentation to describe how to access the data if synchronization fails
    • Alternatively, provide breadcrumb to separate page describing how to access data if synchronization fails
    • Ensure use of search terms such as local, sync failure, offline access, tablet only, etc.
    • Also cross-link that page with the existing Sync Strategies page for System Administrators

• Other notes:

  • There's a confusing double-entry on the left nav menu for data collectors - the data collector entry and the data collector guide entry. The difference between them is unclear. Suggest harmonizing somehow.

[TSSlade]

• Intent: Ticket came to the helpdesk from a user who was unable to upload data, but still had access to the app on the tablet. (They had not yet uninstalled/deleted the app itself.) They were able to provide the .json file via the export

• Load up docs.tangerinecentral.org

  • Effort: Searched for the terms listed below alongside screenshots of the returned results

  • Result: The content lists below

    • import
    • missing
    • lost
    • archive
    • json
    • sync

  • Suggestion: Add documentation - perhaps to the System Administrator section? - about using the import-archives command within the Docker containers to import data from a JSON file. Do a little SEO to link up the idea of JSON files (or local records) being considered archives, connecting import-ing to sync failures, etc.

• Other Notes: If you already know that there is a mechanism to export data to JSON, then searching for that term in the docs returns

  • export One of the breadcrumbs from those results will lead to the Download your data entry, which does not make note of the JSON-export mechanism at all. Linking this up by inserting a mention of that function in this entry would make sense.

[TSSlade]

• Intent: Install / initialize a new repository for local form development
  • 

Looks like we've got some formatting wonkiness in how MkDocs is parsing the markdown for this section

[TSSlade]

Intent: While working on custom functions (for on-open/on-change or components/mystuff.js) related to location lists, understand the structure of Tangerine's locationList objects. Effort:

• Search for locationList in the https://docs.tangerinecentral.org search bar. (No results.)
• Search for Location in the search bar. See many results, most relevantly the INPUT TYPES entries. Result:
• Nowhere in the input types does it describe what a locationList looks like within Tangerine. (It basically says "Here be dragons", which is fine for the average user but is not helpful for would-be devs.) Suggestion (if any):
• Provide example of a locationList as stored within Tangerine. Something like the following:

Blank Location List

{"locationsLevels":[],"locations":{},"metadata":{}} 

Structure of a Populated Location List

{
  "locationsLevels": [
    "<child_of_root>",
    "<grandchild_of_root>",
    "<greatgrandchild_of_root>"
  ],
  "locations": {
    "<parent1.location_id>": {
      "parent": "<{root|parent.location_id}>",
      "label": "<parent1.human_readable_name>",
      "id": "<parent1.location_id>",
      "level": "<parent1.level_name>",
      "children": {
        "<child1.location_id>": {
          "parent": "<parent1.location_id>",
          "label": "<child1.human_readable_name>",
          "id": "<child1.location_id>",
          "level": "<child1.level_name>",
          "children": {
            "<grandchild1.location_id>": {
              "parent": "<child1.location_id>",
              "label": "<grandchild1.human_readable_name>",
              "id": "<grandchild1.location_id>",
              "level": "<grandchild1.level_name>",
              "children": {}
            },
            "<grandchild2.location_id>": {
              "parent": "<child1.location_id>",
              "label": "<grandchild2.human_readable_name>",
              "id": "<grandchild2.location_id>",
              "level": "<grandchild2.level_name>",
              "children": {}
            }
          }
        }
      },
    "<parent2.location_id>": {
      "parent": "<{root|parent.location_id}>",
      "label": "<parent2.human_readable_name>",
      "id": "<parent2.location_id>",
      "level": "<parent2.level_name>",
      "children": {}
      }
    }
  },
  "metadata": {}
}

Example of a populated Location List

{
  "locationsLevels": [
    "region",
    "district",
    "school_name"
  ],
  "locations": {
    "nmlDTIOP": {
      "parent": "root",
      "label": "A Region Name Here",
      "id": "nmlDTIOP",
      "level": "region",
      "children": {
        "htOSqhO8": {
          "parent": "nmlDTIOP",
          "label": "A District's Name Here",
          "id": "htOSqhO8",
          "level": "district",
          "children": {
            "M2IxoJQN": {
              "parent": "htOSqhO8",
              "label": "A School's Name Here",
              "id": "M2IxoJQN",
              "level": "school_name",
              "children": {}
            },
            "LSVLK3lA": {
              "parent": "htOSqhO8",
              "label": "A Different School's Name Here",
              "id": "LSVLK3lA",
              "level": "school_name",
              "children": {}
            }
          },
          "IZu7eTpY": {
            "parent": "nmlDTIOP",
            "label": "A Different District's Name Here",
            "id": "IZu7eTpY",
            "level": "district",
            "children": {
              "7ASAw8gK": {
                "parent": "IZu7eTpY",
                "label": "Name of a School in the Second District",
                "id": "7ASAw8gK",
                "level": "school_name",
                "children": {}
              },
              "PNgRTV6N": {
                "parent": "IZu7eTpY",
                "label": "Name of a Different School in the Second District",
                "id": "PNgRTV6N",
                "level": "school_name",
                "children": {}
              }
            }
          }
        }
      }
    }
  },
  "metadata": {}
}