How to link many large strings in a maintainable way

Question

I'm developing an app that will work as a troubleshooter. In this, I want to ask the customers only relevant questions instead of giving them an exhaustive list.

Every option they choose will have to be linked to a new question with only a few answers, so I can distill the issue they are having effectively and without them having to try 10 different things or answering 20 questions that have little to do with the issue and amount to nothing in the end (hello Windows troubleshooter).

I have made the framework in HTML which was easy enough but the biggest thing to do is store all the strings and connect them together in a somewhat clear way, like a diagram or something. Right now, I can only think of populating a DB with the sentences but the linkage will be chaotic as hell.

So, the only question I have is: Does anyone have an idea on how to do this in a better way, perhaps some kind of visual representation software?

I tried, as a test, to add the strings as objects in a json, which works well but the linkage already got super chaotic when I went above 50 strings ish, and I will be needing much more (thinking 1000 ish at least).

Thanks in advance for any input.

=============
EDIT: Oh wow, lots of answers, thanks all! It seems like most answers are similar, and it looks like that is what I already have. Thanks for the suggestion on YAML, I will check it out.

I made a JSON structure initially without giving it too much thought, I wanted to focus on the framework first.

I guess I will need to input a lot of data anyway, so I'm not sure if I am just wasting your time and this is as good as it gets.

The thing is, many questions will lead to the same answers, so I'd like to inter link those. I have this working with the JSON structure now.

JSON with lots of objects like:

{
     "ID": "3.16",
     "Step":"Have you tried turning it off and on again?",
     "NextStep": ["3.17", "3.18"]
},

So, if step 3.16 is triggered it will show this text and if a person says yes to that, it will show step 3.17 and 3.18

This method of inter- and cross-linking works, but get's chaotic so I just wondered if there was a better way that I am missing.

I like the DX diagnosis suggestion as well, but this does not make the structure simpler it seems? But I will probably add that as the weights would be very good to have.

Answer 1

Hi and welcome to the board :)

I'm not exactly sure if I understand your question correctly, so let me rephrase it in my own words:

I want to help customers to troubleshoot their problems on their own. To help them to get to the right answers, I'm creating a drill-down menu where each question leads to a more detailed question, until the system can provide a answer. Something like:

1. Question: What is your Problem? Answer: I forgot my password
2. Q: What system did you loose access to? A: My Computer (Windows Password)
3. Q: Do you still remember your recovery token? A: No
4. Action: Please call IT support: 01234-12345.

To keep it small and simple, I would suggest a very simple JSON-Structure. No linking, no magic. Something like:

//leading question: What is your Problem?
const data = 
[
  {answer: 'I forgot my password',
   next:{
     question: 'What system did you loose access to?',
     answers: [
       {answer: 'My Computer (Windows Password)',
        next: {/*..*/}
       },
       {answer: 'Google (Web password for google services)',
        next: {/*..*/}
       },
       ]
   }
   },
  {answer: 'My computer does not work',  next: {/*..*/}},
  {answer: 'I have a problem with a specific program', next: {/*..*/}},
]

Even though you might have 1000ths of items in it, I guess it is still the simplest approach. I would suggest using a json schema to prevent errors.

Answer 2

Given that this appears to be immutable metadata that drives the flow of the application rather than user data, it seems like it'd need to be the same in all environments, therefore worth treating it as a static asset committed alongside the source code, rather than loading it into a database (which adds deployment complexity as well as losing any guarantee of consistent structures between your environments).

You could consider representing it in an simple object modelling format such as JSON or YAML, committed alongside the code where it'd likely be easier to include in your automated testing as well as ensuring local development remains consistent with all other environments:

questions:
  q1:
    text: What is your name?
    possible_answers:
    - a1
    - a2
    - a3
  q2:
    text: What is your quest?
    possible_answers:
    - a4

answers:
  a1:
    text: King Arthur
    next_question: q2
  a2:
    text: Galahad
    next_question: q2
  a3:
    text: Robin
    next_question: q2
  a4:
    text: Find the Holy Grail
    next_question: q3

A lot of configuration management tools use YAML for the human-readability of the format - particularly the support for comments.

Answer 3

There is a rich DX diagnosis literature which covers topics like fault equivalence and diagnosibility. We have a system-under-test that is stimulated by an input vector and is comprised of components. We observe various outputs. A bad output often means we cannot achieve the goal state.

For example, a vehicle might need fuel and working transmission components in order to achieve highway speed, or to even leave a parking space. The diagnostic tasks are to verify each of the preconditions. Or sending a payment might require a positive balance and proper credentials, where again we can verify each of them.

For the various high-level goals a troubleshooting system wishes to support, it can record

1. components needed to support the goal
2. diagnostic tests that verify component health

Clusters of related goals often rely on common components, so a tree or other graph datastructure is often appropriate for (1.). The tests can be a combination of automated observations (ping) requiring no interaction, plus Q / A responses elicited from the customer.

The simplest approach is to just "ask everything!", even questions irrelevant to the goal, and isolate the faulted component. That is excessive, so we impose a cost function to minimize effort & risk. For example we might run all automated probes initially, and then a few seconds later we have gathered some diagnostic information at almost zero cost. Then we are faced with asking a series of questions that reduce uncertainty, narrowing the field of potentially faulted components.

Some faults are more common that others. It is better to rule them out first. Some tests are cheaper than others, e.g. "read this screen" vs "reboot". So each question should be tagged with a few attributes: prevalence, and cost to perform the test. That lets a Planner navigate the graph to identify the next test, the next question, that in expectation will arrive at a successful diagnosis. A Decision Tree can encode these concerns in a static way. For components that interact in a complex manner, dynamic re-planning of the questions to ask can arrive at a diagnosis with lower cost.