Tech Writing: Returning to point where user left off in instructions
Hello,
For a web application, documented in a Wiki, I have a data element (call it THING) which can contain one or more WIDGETS There exist two places in the instruction set for THING where I refer the user to the separate instructions for WIDGET.
TO ENTER A THING:
1. blah blah blah
2. Enter a Widget. Click here for info. ("Here" takes you to a separate section for widget entry,))
3. To generate additional sequential widgets (one more month)
a. Click "GENERATE SEQ"
b. Enter number of Widgets
c. For each month, enter a widget. Click here for info.
4. Enter notes for the Thing.
5. Click OK to Save.
My instructions to enter a widget are somewhat involved, and, in the interest of "reusability" are contained in their own section.
Widget Entry: (located in its own section which I can link to.)
1. Enter cost.
2. Enter date.
3 etc.
4 etc.
To my question: after user completes step 4, I want him to return to the "Thing" instruction at the point where he left off. (which could be one of two places. How can I best handle this situation. I see two possible ways:
1. Say nothing, and trust that the reader will know to click the BACK Button to return to where he left off in the instructions.
2. Write something like "Return to Enter Thing instructions where you left off" to gently nudge him to hit the BACK button. (To avoid the temptation for wandering eyes to continue with the next section in the document.)
Thanks,
Steve
For a web application, documented in a Wiki, I have a data element (call it THING) which can contain one or more WIDGETS There exist two places in the instruction set for THING where I refer the user to the separate instructions for WIDGET.
TO ENTER A THING:
1. blah blah blah
2. Enter a Widget. Click here for info. ("Here" takes you to a separate section for widget entry,))
3. To generate additional sequential widgets (one more month)
a. Click "GENERATE SEQ"
b. Enter number of Widgets
c. For each month, enter a widget. Click here for info.
4. Enter notes for the Thing.
5. Click OK to Save.
My instructions to enter a widget are somewhat involved, and, in the interest of "reusability" are contained in their own section.
Widget Entry: (located in its own section which I can link to.)
1. Enter cost.
2. Enter date.
3 etc.
4 etc.
To my question: after user completes step 4, I want him to return to the "Thing" instruction at the point where he left off. (which could be one of two places. How can I best handle this situation. I see two possible ways:
1. Say nothing, and trust that the reader will know to click the BACK Button to return to where he left off in the instructions.
2. Write something like "Return to Enter Thing instructions where you left off" to gently nudge him to hit the BACK button. (To avoid the temptation for wandering eyes to continue with the next section in the document.)
Thanks,
Steve
ASKER
Chinmay, I realize I wasn't entirely clear in my question. Did you understand it to mean clicking BACK in the Wiki doc as opposed to the documentation?
If so, what's the solution here to make sure he returns to where he should return in the directions?
Thanks.
If so, what's the solution here to make sure he returns to where he should return in the directions?
Thanks.
If it is a digital document(HTML, Word, PDF) then leave a reference to the location where he should return. So my suggestion would be to still use second option, leave an instruction / bookmark to return to the right point where he should start again - otherwise most readers will end up struggling.
ASKER
Problem is that this instruction set can be "called" from three different places in the THING instruction set...
That is ok, I believe this is a digital document, so you can put it in a single location and have reference to it from all the three locations. If there is a procedure that is repeated multiple times, put it under a separate heading and give a link from all the locations, you would need those instructions. So none of the three places, a 4th place where the instruction will actually reside.
ASKER
RIght, but how do you maximize the chance that user will return to each of the three places which links to the Widget instructions. For that matter what if these instructions are referenced from 10 places spanning 3 documents?
Thanks.
Thanks.
Reading these document/s in entirety will help user right? We can't enforce that they read through unless you use some app. So we have to provide enough instructions for them to refer to this information. Also, all the well known document types support cross document references so you are safe from that angle as well.
Hi Steve,
I would put an instruction to "return back" in each instruction that says to go "here". In other words, something like this:
TO ENTER A THING:
1. blah blah blah
2. Enter a Widget. Click here for info. Return back here after entering a widget.
3. To generate additional sequential widgets (one more month)
a. Click "GENERATE SEQ"
b. Enter number of Widgets
c. For each month, enter a widget. Click here for info. Return back here after entering a widget.
4. Enter notes for the Thing.
5. Click OK to Save.
If there are 10 places spanning 3 documents, keep doing it, e.g.:
TO ENTER THING AGAIN
1. blah blah blah
2. Enter a Widget. Click here for info. Return back here after entering a widget.
3. blah blah blah
I did something like this recently in one of my programs...it is a client-side program, not a web app, but the idea is the same, i.e., put up a "return back here" or "come back here" comment. Here's the actual dialog from my program:
In the case of a web app (unlike mine), you could be even more explicit with the instruction to make it clear to hit the Back button in the browser, something like this:
2. Enter a Widget. Click here for info. Hit the Back button in the browser to return here after entering a widget.
Regards, Joe
I would put an instruction to "return back" in each instruction that says to go "here". In other words, something like this:
TO ENTER A THING:
1. blah blah blah
2. Enter a Widget. Click here for info. Return back here after entering a widget.
3. To generate additional sequential widgets (one more month)
a. Click "GENERATE SEQ"
b. Enter number of Widgets
c. For each month, enter a widget. Click here for info. Return back here after entering a widget.
4. Enter notes for the Thing.
5. Click OK to Save.
If there are 10 places spanning 3 documents, keep doing it, e.g.:
TO ENTER THING AGAIN
1. blah blah blah
2. Enter a Widget. Click here for info. Return back here after entering a widget.
3. blah blah blah
I did something like this recently in one of my programs...it is a client-side program, not a web app, but the idea is the same, i.e., put up a "return back here" or "come back here" comment. Here's the actual dialog from my program:
In the case of a web app (unlike mine), you could be even more explicit with the instruction to make it clear to hit the Back button in the browser, something like this:
2. Enter a Widget. Click here for info. Hit the Back button in the browser to return here after entering a widget.
Regards, Joe
ASKER
Joe,
Just to be clear Your instruction to "hit the back button" refers to the documentation itself; not the application, right?
In that case, wouldn't it make more sense to write "hit the back button" at the end of the Widget instruction set?
My concern is that if the instruction set for Widgets is long, users may forget to "return back here".
Thanks.
Just to be clear Your instruction to "hit the back button" refers to the documentation itself; not the application, right?
In that case, wouldn't it make more sense to write "hit the back button" at the end of the Widget instruction set?
My concern is that if the instruction set for Widgets is long, users may forget to "return back here".
Thanks.
ASKER
You know what would be really cool? Somehow to have a "back to previous instruction" link at the end of the Widget documentation. Where the link would be dynamic, and remember where you came from.
Hi Steve,
> In that case, wouldn't it make more sense to write "hit the back button" at the end of the Widget instruction set?
Yes, if that's the case, but I didn't think that was the case for you. I may not be understanding your workflow. In my case, the instruction (in the app) takes you to the doc, and the instruction (in the app) makes it clear that you need to return to the app after viewing the doc. I thought that was your situation, too, although the app in your case is a web app, while in my case, it's a client-side app.
> the link would be dynamic, and remember where you came from
Yes, that would be cool, and in programming, that's easy. It's usually called a function or subroutine. When you call a function or subroutine, it does its thing, and then returns to the caller (usually via a Return statement, but, of course, that depends on the programming language). Do you have any programming structures like that (functions or subroutines) in the platform that you're using for this project? Regards, Joe
> In that case, wouldn't it make more sense to write "hit the back button" at the end of the Widget instruction set?
Yes, if that's the case, but I didn't think that was the case for you. I may not be understanding your workflow. In my case, the instruction (in the app) takes you to the doc, and the instruction (in the app) makes it clear that you need to return to the app after viewing the doc. I thought that was your situation, too, although the app in your case is a web app, while in my case, it's a client-side app.
> the link would be dynamic, and remember where you came from
Yes, that would be cool, and in programming, that's easy. It's usually called a function or subroutine. When you call a function or subroutine, it does its thing, and then returns to the caller (usually via a Return statement, but, of course, that depends on the programming language). Do you have any programming structures like that (functions or subroutines) in the platform that you're using for this project? Regards, Joe
ASKER
Joe,
As a (former) developer, I'm well aware of calling functions and subroutines. That said, i guess I wasn't super-clear in my question. The workflow I'm struggling with is per navigating through our wiki only. (In fact, I don't think there's one instruction in our documentation that tells the user to hit the BACK BUTTON from within the application.)
I'm sure I;m not the first tech writer to encounter this dilemma so there has to be a reasonable solution out there.
I just went back to a document I wrote a couple of years ago.
1. Enter item name.
2. Select department (which is a link to instructions elsewhere)
3. Enter cost.
4. etc.
I took a look at the "Select Department" instructions and this is how I handled it:
,<Steps 1 to 7 are here>
8, Resume the process for which you selected the department.
When I wrote that sentence a couple of years ago, I may have been operating under the assumption that the user would know enough to hit the BACK button in the browser.
As an alternative, I suppose I could do the following. At the last step in the "subroutine" instruction set, have something like this.
8; Proceed as follows:
> If you were entering a single widget, click here.
> If you were entering multiple widgets click here.
> If you were editing a widget, click here.
The above would be technically accurate, but, perhaps, unwieldy. (e.g. if I added a fourth ref. to this instruction set, I'd have to remember to update step 8.....
Thanks.
As a (former) developer, I'm well aware of calling functions and subroutines. That said, i guess I wasn't super-clear in my question. The workflow I'm struggling with is per navigating through our wiki only. (In fact, I don't think there's one instruction in our documentation that tells the user to hit the BACK BUTTON from within the application.)
I'm sure I;m not the first tech writer to encounter this dilemma so there has to be a reasonable solution out there.
I just went back to a document I wrote a couple of years ago.
1. Enter item name.
2. Select department (which is a link to instructions elsewhere)
3. Enter cost.
4. etc.
I took a look at the "Select Department" instructions and this is how I handled it:
,<Steps 1 to 7 are here>
8, Resume the process for which you selected the department.
When I wrote that sentence a couple of years ago, I may have been operating under the assumption that the user would know enough to hit the BACK button in the browser.
As an alternative, I suppose I could do the following. At the last step in the "subroutine" instruction set, have something like this.
8; Proceed as follows:
> If you were entering a single widget, click here.
> If you were entering multiple widgets click here.
> If you were editing a widget, click here.
The above would be technically accurate, but, perhaps, unwieldy. (e.g. if I added a fourth ref. to this instruction set, I'd have to remember to update step 8.....
Thanks.
OK, I'm really not understanding. I thought the situation was that someone using a web app would click a link that goes to doc in a wiki. After reading the doc in the wiki, the user would return to the web app to continue using it. Now I think you're saying that there's no app involved at all in the workflow...only the doc in the wiki:
navigating through our wiki onlyIs that right?
ASKER
Yeah,(s) he may well have the application open in another tab. The only workflow I care about is following our instructions, navigating through our wiki only. Apologies for for any confusion. :)
ASKER
And one more point. Here and there, I link to a definition of a term
e.g.
3. You can enter a price no higher than your remaining budget
4. Enter the ceiling price.
5. etc.
Here, the text per "remaining budget" is explanatory only with no directions. It just defines the term, and user would then resume following the instructions. For something as simple as a definition, how would that work in terms of going back to where you came from? Thanks.
e.g.
3. You can enter a price no higher than your remaining budget
4. Enter the ceiling price.
5. etc.
Here, the text per "remaining budget" is explanatory only with no directions. It just defines the term, and user would then resume following the instructions. For something as simple as a definition, how would that work in terms of going back to where you came from? Thanks.
ASKER
Hey Joe did u see the above? Thanks!
ASKER CERTIFIED SOLUTION
membership
This solution is only available to members.
To access this solution, you must be a member of Experts Exchange.
ASKER
Joe,
That's a great idea. I'll have to see if our wiki supports opening in mewwindow: that; would certainly make more sense. Guess I'm so immersed in these articles that I was too close to the situation to see that obvious workaround. Will let you know how it works. :)
Thanks for taking time out of your busy day to lend a hand.
That's a great idea. I'll have to see if our wiki supports opening in mewwindow: that; would certainly make more sense. Guess I'm so immersed in these articles that I was too close to the situation to see that obvious workaround. Will let you know how it works. :)
Thanks for taking time out of your busy day to lend a hand.
Always happy to help...when I can. :)
ASKER
I'll let you know how it turns out.
Thanks...I'm curious!
ASKER
Well, mechanically it seems to work (brings up the linked-to content in another tab. I'll have to run it by my supervisor to see if he's on board with this method, which we have not been using to date, but I like it.
For any of the links that take you to an instruction set, I'm adding a line that says something like:
"Resume the process for which you entered the widget".
Only problem I can see is that in Zendesk (which I'm currently using) there's a checkbox for opening in new tab, and I haven't tested all the permutations. (ZD supports a few different types of iinks.) In Confluence, which we also use, I haven't seen such an option.
Probably won't have any more to report until Monday (or maybe Tuesday, when I have my weekly doc review with my supervisor.). But, odds are that I'll select your comment as the solution.
Thanks, and have a good weekend.
For any of the links that take you to an instruction set, I'm adding a line that says something like:
"Resume the process for which you entered the widget".
Only problem I can see is that in Zendesk (which I'm currently using) there's a checkbox for opening in new tab, and I haven't tested all the permutations. (ZD supports a few different types of iinks.) In Confluence, which we also use, I haven't seen such an option.
Probably won't have any more to report until Monday (or maybe Tuesday, when I have my weekly doc review with my supervisor.). But, odds are that I'll select your comment as the solution.
Thanks, and have a good weekend.
Sounds good. You have a good weekend, too.
ASKER
Thank you both. While I really liked the "open in new window" option, my manager vetoed it. Still I think it's a worthwhile option as long as the wiki you're using to create these docs supports "open in new tab".
Of course, there's nothing to prevent users from right-clicking the link and opening in new tab manually. :)
And, where appropriate, I wrote a gentle reminder to resume the previous directions.
Of course, there's nothing to prevent users from right-clicking the link and opening in new tab manually. :)
And, where appropriate, I wrote a gentle reminder to resume the previous directions.
> While I really liked the "open in new window" option, my manager vetoed it.
To be clear, I proposed "open in new tab", not "open in new window" — having many windows would be messy.
> as long as the wiki you're using to create these docs supports "open in new tab"
Exactly!
> Of course, there's nothing to prevent users from right-clicking the link and opening in new tab manually. :)
Yes, as I mentioned earlier, that's what I do when the doc doesn't do it by default.
> I wrote a gentle reminder to resume the previous directions.
Great, as long as you were gentle. :)
To be clear, I proposed "open in new tab", not "open in new window" — having many windows would be messy.
> as long as the wiki you're using to create these docs supports "open in new tab"
Exactly!
> Of course, there's nothing to prevent users from right-clicking the link and opening in new tab manually. :)
Yes, as I mentioned earlier, that's what I do when the doc doesn't do it by default.
> I wrote a gentle reminder to resume the previous directions.
Great, as long as you were gentle. :)
I have never seen that one working ... like... ever.
Regards,
Chinmay.