# Stepwise procedures to guide users through testing

by Sreyanth | 14 Jul 18:06

Sreyanth was awarded the Basic Barnstar by liz for their work in this research note.

### What I want to do

I wanted to create a new module for SpectralWorkbench, to guide the users through testing, and also help them document their work in a well-mannered fashion. This also attempts to reduce manual intervention as much as possible, by automating several steps.

### My attempt and results

With the help of Jeff, I could identify the common steps that the users go through while attempting to test any material. This was done by reading many notes posted here about testing. This was quite time consuming and at the end of this exercise, I had a list of several steps that appear in almost every test.

So, I went a step further ahead, and created a HTML mockup of what the interface should ideally look like (a lot of tweaks, and coloring needs to be done, but this is the basic idea), and this is how it looks:

This would be the recording interface for the procedure, where the user can choose to record a live testing experiment, or can choose to use the existing data (may be an already existing spectra on SWB, or just images, or any other format for that matter).

The text area would be like the one we have on the PublicLab.org site to post the research notes. This would let us to include images, have markups, links etc.,

And, to showcase our content, we would have a dedicated page, probably like this:

### Questions and next steps

I would love to hear your feedback on the interface, and let us (Jeff and me) know what could be done better, so that I can re-iterate this and probably work on a beta version that I plan to release soon.

Interesting! How would "add a missing step" work -- would anyone be able to add one, or is that just for the author of the procedure?

Is this a question? Click here to post it to the Questions page.

And for procedures involving actually taking a scan, would it pop up the capture interface, then close it again once you take a spectrum?

Is this a question? Click here to post it to the Questions page.

Hi Jeff. "Add a missing step" will work only for the author of the procedure. The comments section would always open up the opportunity to let the author know about anything (s)he might have missed.

This feature has been added to recognize the fact that all the testing procedures are not the same, some may require addition steps, and some might not require the ones we listed out (in which case, they can click on "Skip this step").

I was thinking like this. For procedures involving actually taking a scan, see the "Capture the spectrum and tag to this procedure" checkbox under live feed section? Once that is checked, the capture interface would appear as a

element in the place of the textarea we currently have, pushing it downwards. The spectrum can be captured & saved here (would make great sense once the macros module is implemented).

This is how it would probably look like. (Just rough drawing for the idea; Not all options like save, adjustments, tools are depicted here)

I like the idea of popping up the interface, and then close it again once done - but refrained from it to avoid popup blocking & managing issues. If that entails better usability, we can do that :)

Is this a question? Click here to post it to the Questions page.

I like "tag to this procedure" - would it have a power tag like procedure:13431 ? We have to have procedure_ids as well as instance ids, since people will "run the procedure" multiple times. When you open a procedure, i assume it'd pick up at the last unfinished step?

Once the capture happens, if it has a procedure tag, it'd redirect you back to the procedure?

Is this a question? Click here to post it to the Questions page.

I was thinking of adding the spectrum tag to the procedure (as it may so happen that the user may want to retrospectively write procedures). I didn't get the "run the procedure" multiple times part. Can you please tell me more? Yes, I am keeping track of the state of the procedure, so that the user could pickup at the last unfinished step. We could add an autosave feature, if need be.

In the present design, the capture happens in the procedure dashboard itself, so I don't think the redirect part is applicable. (or did I miss something? :-o)

Is this a question? Click here to post it to the Questions page.

Well, someone will be able to publish the procedure, but many people will use it. To store the current state of the procedure, so that people can "return to it" and we can store aggregated data generated by the procedure, we'll need both the procedure template and the procedure "run", which stores one copy of someone having actually run through the procedure, make sense?

I guess we'd just want to be sure there's a consistent design between the "inline capture" you're proposing and the overall capture interface. We might want to start just by redirecting to capture with some parameters (like 'procedure_run=32432'), and redirecting back, so that we don't have to refactor the capture interface to work inline. Later, we can refine that to be more seamless. How about that?

Is this a question? Click here to post it to the Questions page.

Ah. I get the "run" part now. The publisher of the procedure probably has some data associated to the procedure. The data generated when the procedure is run would store as a copy, and tagged to the user. Am I on the correct path?

I thought the inline capture is simple, more so with the API coming up. But yes, this could be resorted to at the later stage. Popping up has better UX than redirection, don't you think?

Is this a question? Click here to post it to the Questions page.

The publisher of the procedure probably has some data associated to the procedure

Well, the procedure itself might or might not reference data. But anyone who goes through the steps of the procedure will surely generate data. It's the difference between a template and the thing you make with a template. Make sense? We need good vocab for this: procedure vs. procedure run ?

Popping up in a new browser window? Yes, i think so. But you'd have to AJAX poll on the procedure page to check if the user has completed capturing the spectrum.

I had guessed that the spectrum would need a foreign key of the procedure run -- perhaps via a tag. In the sense that the spectrum would "belong to" the procedure run.

Is this a question? Click here to post it to the Questions page.

Oh, I think I now get the vocab. So the template merely consists of the steps, it may (then it would be the first procedure run) or may not have data associated with it. In that case, every non-cloned (or something that hasn't been run from existing template) procedure would be a template. Is that right?

I guess we can just listen to window.close() and resume the procedure? But, I was thinking of the redirection to be a good thing when browsers have the popup blocking issues.

Yes, a spectrum "belongs to" a procedure run, agreed. But having a foreign key to the spectrum would only lets me identify the procedure run. But I wanted to keep a track of all the spectrums that belong to the procedure run at various steps. Probably, the other way round is a better DB design?

Is this a question? Click here to post it to the Questions page.

Procedures would only have data if, for example, one step was to compare it to a known spectrum, or look at it alongside a set. A ProcedureRun would store all the data produced by someone walking through the steps of a Procedure.

Listening to window.close() might not be as good as actually generating a unique key for a spectrum which would link it back -- what if they want to do the scanning on a different machine? Like with a smartphone? Why don't we:

• Initiate a Capture window load with /capture?for=<id>&key=<key> where <id> is the primary key of the ProcedureRun and <key> is the key of the request (assuming there could be multiple captures requested)
• the Capture window would append a tag for:<id>:<key> or maybe separately for:<id> and key:<key> or something? We could start to hide this kind of tag from the user unless they really want to see it
• the Procedure interface would poll the server every 3 seconds for /spectrums/<id>/key/<key> until it returned a spectrum_id
• the it would go to the next step

all the spectrums that belong to the procedure run at various steps

Maybe we mean the same thing. The spectrum would have the tag as a kind of crude join table. The tag would include the ProcedureRun id. Doesn't make the above possible?

Is this a question? Click here to post it to the Questions page.

I think I am missing out something here. When a user creates a Procedure, (s)he just writes the text as to what is to be done, and not actually running the Procedure?

If we have a key of the request stored with the spectrum, then yes. I started implementing the system and will update how it goes.

Is this a question? Click here to post it to the Questions page.

Yes, imagine for the oil testing kit. We want everyone to follow the same procedure, so we post the procedure. Then 20 people each go through the steps and record 20 unique datasets, each of which was generated by following the original procedure. Make sense?

Is this a question? Click here to post it to the Questions page.

Completely! So, if I were to run a new procedure of my own, I would first create its template, and then run it. That's the model isn't it?

Is this a question? Click here to post it to the Questions page.

Yes - and when you run it, the data is stored in a ProcedureRun table, not in the original Procedure. That's the distinction I'm talking about - but maybe we're on the same page?

Is this a question? Click here to post it to the Questions page.