Mother. Writer. Editor. Home Minister. All roles in one. That’s Prajakta Pradhan. She loves to be busy at work, creating new documentation, editing the work of others, and conjuring something new. Inclined towards information mapping and minimalism, she has recently started learning design thinking, and is excited to use that in her writing and bring in some innovation.Prajakta Pradhan
A 2-act play. Characters, in the order of their appearance:
Information Developer Manager
Evening. Ajay and Manasi are sitting in a small conference room. Ajay dials into a conference call.
Hello, who's joined the call?
Hi, this is Alfred.
Hello Alfred. This is Ajay and I have Manasi with me.
So Manasi, where are we with the restructuring of the User Guide?
I've already prepared the TOC and shared it with you, Alfred. Did you get a chance to go through it?
According to me, the guide should have all screenshots of the UI that the user will be accessing. The user needs to know where he is when he is doing the tasks. Our product is a very complex product and users require assistance while using it. We cannot assume...
Hey Alfred, hang on for a minute. I don't think I agree to your idea of adding screenshots. Our procedures are clear enough to understand how to proceed with the tasks.
Yes, that's true. Our procedures provide clear information about where to perform the tasks and how to proceed. And with the restructuring, we are ensuring that users get the required information without searching too much for it.
You see, our product is complex. Users need to see where they are exactly, or where exactly to navigate to when they are doing the tasks.
And we are working on the structure just for that. We are planning to add workflows and breadcrumb graphics to show where users are while they are completing tasks.
In case of our users, we must consider that they are novice users.
Alfred, this is where I totally disagree. We cannot consider that users of our products are novice users. To install and use our product, knowledge of databases and servers is required. If we expect users to know how to manage and use them, we cannot assume that they are novice users.
But we use third-party products for installing and using our product. And our methods to install the third-party products are different than the standard ones.
So then, we ought to document those points that show how we are different.
That is where screenshots are required.
No, I don't agree. I am not ready to add screenshots. Let me ask you one question. Have you gone through the new TOC that Manasi shared?
I know our guide. Based on that, I am saying that our document is very complex to understand and needs to be simplified by adding screenshots. Perhaps not every step needs a screenshot. But at least in the places where users might get confused, we ought to add screenshots.
Alfred, I think the problem here seems to be that our product is complex. I don't think that's going to be resolved by adding screenshots.
We already have several documents that my team has prepared that contain the screenshots. We shared them with you and we want you to use those documents for restructuring the guide.
Yes, we have them. And Manasi has used the same documents to compare what's missing in our guide and come up with a comprehensive TOC.
Alfred, I think we ought to sort this issue about screenshots before we proceed. I suggest that you go through the new TOC and let us know your thoughts. We'll schedule a meeting again to discuss this. We've already exceeded our meeting time. Manasi, will you schedule a follow-up meeting for half an hour next week?
Sure, will do.
Alright, thanks Alfred. We'll talk to you next week.
Okay, thanks. Bye.
The call ends.
Alfred is being unreasonable. I also don't think he has gone through the new TOC that you prepared. I cannot understand how he can say that we deal with novice users.
Well, that's what "refactoring" is for him. Just add screenshots and all problems are resolved!
Apparently! Let's wait and see what he has to say in the next meeting.
See, it's one thing to just say include screenshots, which all developers and QAs say. It's another thing to say it because you haven't done audience analysis. Or should I say, because you refuse to recognize who's the user.
When I installed the product with the help of the QA, I had to rely on his understanding of databases and servers. So obviously, the product can't be used by novice users. And if there aren't novice users, screenshots don't matter.
No Manasi. It's not about having screenshots because of novice users. These are two different issues according to me. The first issue is about novice users. We both agree to the fact that the product is not for novice users. The second issue is about screenshots. It is high time we all, as the IT community, realise that we've now come a long way from what our audience was 10 years ago.
Ten years ago, the average user did not know much about computers and internet. It was imperative then to provide detailed instructions, give screenshots, spoon-feed users about how to complete tasks. But now, the average user is the one who uses smartphones and tabs, and owns multiple gadgets. Even a child now knows how to use a smartphone. It's now easier in fact to provide documentation because it's not required at that basic level.
What do you think?
I think you are right. But I would like to disagree with what you are saying about it being easy to create documentation. I think it is far more challenging. If all users are smart, we need to present our documentation in a way that attracts them and helps them find the right information. Presentation and structuring acquire a lot of importance.
Yes, you are right. [A short pause.] Anyway, coming back to Alfred...I think you should also have another look at the TOC to see if there's any different presentation or structuring that will help Alfred understand that we are restructuring the guide in the way he was hoping, minus the screenshots of course.
Alright, will do.
Thanks for your work on this, Manasi. You are doing a fine job.
Thanks much, Ajay.
Both leave the room.
The next day. Manasi is in the canteen, talking over tea to her colleague, Preeti.
So how was the call?
The usual...Alfred going on and on about refactoring and screenshots.
Why's he so adamant about screenshots? What is his problem?
I don't know. Frankly, I don't want to know!
But seriously, Manasi, what do you think? Can you understand what he wants?
In a way, yes. But not entirely. I understand he wants to 'refactor' the guide. As per my understanding, it's really rearranging the information and restructuring the topics. And everyone is just so used to having screenshots that it's quite an unlearning to see docs that don't have any.
Why don't you just present it differently and call that refactoring?
What do you mean?
I mean, I think missing screenshots is Alfred's way of solving the problem. Why not provide lots of workflows and cool stuff and call that refactoring? Besides workflow and other restructuring, was there a lot of information missing from our docs?
Actually, no! When I compared the documents that his team had shared with our existing guide, I found that there's really very little that we haven't included in our guide. The flow is missing for sure. But not a lot of information. In fact, it's all there. Just not visible. And because of the non-visibility, they need the help of screenshots.
So you are saying that I should present it differently and call that 'refactoring'?
Okay, I'll have to figure out where and how to fit in the workflows, and any other diagrams and the cool stuff!
You should also talk to Ajay. May be he can give some ideas.
Yes, let me do that. Shall we go?
Both leave the cafeteria and return to work.
Two days later. Manasi walks up to Ajay's desk for a discussion.
Hi Ajay. Got a few minutes?
Sure, give me a moment.
Ajay reads through a mail on his screen, nods satisfactorily, and sends it across. He then turns around to face Manasi.
Well! I wanted to discuss the refactoring of the user guide.
Okay, do you want to go to a room?
No, this is fine. It won't take long. So what I did was...I spoke to Viraj from the support team. I asked him if he or his team had used our user guide for understanding the features and how to accomplish tasks.
He said they had. I asked him the trouble they had with the guide. Whether there was no information available, or incorrect information, or whatever.
I see. What did he have to say?
So he said that they could find the information in the guide, but that it was not easy to locate it. I suppose he meant that there isn't a good flow. The information is all scattered. Because they have been using the product for some time, and also the documentation, they could figure out where to find what. But otherwise, it's a bit difficult to find the information.
So what it means is that if I introduce a proper flow, and workflow diagrams, the doc should look good.
So what it means is that if I introduce a proper flow, workflow diagrams, appropriate links, the doc should look good.
Tell me, you had compared the docs that Alfred's team had given, right?
And how much of information is missing?
Not much really.
Can you tell that in number of pages?
Not more than two pages. Their documents are full of screenshots, which we aren't using. But the real information that's not there in our guide is not more than two pages. And that too not at a stretch. I mean, there isn't a whole topic that is missing. It's more of minor points that are missing in some sections. And all that does not add up to more than two pages.
And Viraj said that workflow is missing.
Yes. I'll have to quickly come up with some good workflows to connect all the dots. One main workflow that gives an end-to-end process. And other smaller ones wherever required.
How many smaller workflow diagrams do you think are required?
I think three.
So four in total. Are you planning to show this to Alfred in our meeting on Tuesday? All four of them?
Yes, I want to.
Manasi, I think you should stick to the main workflow. Considering it's Friday today, you have got only two days to create the workflow. So I suggest, just create the main workflow. Put a placeholder in the other places where you know you'll create them. And then can you do something else too? Can you create a quick presentation for Alfred? I would like you to include the comparison of the TOC before and after the refactoring, the feedback from Viraj, the restructured TOC and how it is better now, and the last point is how screenshots are not going to help.
I can do the presentation. But I didn't get your last point.
Yes, I was rather cryptic. List the points that show that it's not a good idea to have screenshots: translation cost, user experience.
Okay. I'll prepare that and run it through you before presenting it to Alfred.
Great. So Ill work on the workflow then and also the PPT.
Thanks. Let me know if you need any other help.
The meeting ends.
The following Tuesday. Ajay and Manasi are sitting in a conference room.
Hi, is that Alfred joining?
Hi. This is Ajay and I have Manasi with me.
Hi. How are you?
So Alfred, are you logged on to the online meeting? We would like to present.
Yes, I am already on.
Okay. I am going to hand over the sharing to Manasi. Here you go.
Alright, so here's what I would like to show. On the first slide of the slide deck, our pain-points: Information is scattered, no workflow, too much information.
So how have we addressed them? By refactoring the guide. We have done a major overhaul. Here's our old guide, the TOC. And here's the new TOC. As you can see, we have made major changes to it. The guide is now restructured based on tasks rather than the features.
Hey, can you hold on to that screen for a second. I just want to go through it.
Okay, that looks pretty good. It certainly provides a good flow. And it kind of now falls into place. So this all information has now come from the docs that my team shared?
Not exactly, Alfred. I have consolidated the information from your docs and the existing guide. Most of the information from your docs was already available in the guide. Only, it was too scattered and inaccessible. I have cleaned it up quite a bit, and this is what it looks like now.
Okay, and the screenshots are included?
I'll come to that in a minute.
Okay. Go ahead with the presentation, Manasi. I'll park my questions for now.
Right. Here are the different workflow diagrams that we have proposed. This is the main workflow that I have already created. It gives a comprehensive idea of the entire end-to-end process. It also gives links directly to the topics that contain the task procedures. But I would like to elaborate on how the workflows will be useful, so just hang on while I open the actual document.
Can you see this online help page?
Okay. So here's the TOC. Here's the main workflow. Here on the top, you can see all links to the various topics. At each step, I'll create a workflow to show where the user is in the entire process. So rather than having the screenshot of the UI, the user can navigate back to the previous task, or jump to the next task with the help of these links.
Alfred, I spoke to Viraj and tried to understand how the doc is used. He said the main pain point was a lack of flow. The information was all there. I also asked him if screenshots would be useful. And he said only to a limited extent.
You see, the user guide will be available online while performing tasks on the UI, so the UI is already open before the users. The user guide is easily accessible. So instead of screenshots, these workflows will help users navigate between tasks.
So the workflows can be used to navigate between tasks. But if I am on a page, how do I know what's my previous or next task?
We plan to use the workflows on each page, as breadcrumb graphics.
Could you elaborate on that?
Sure. Manasi, can you show that page where you added the graphic?
Yes. Here we are. So right at the top, I've added the image that shows the user's current location in the workflow.
Aaah! This looks cool!
And Alfred, our user guide is bundled together with the product as online help. It is also context sensitive. So each page has its own help page. It seems redundant to show the UI screenshot again in the help. It's like the snake-eats-its-own-tail kind of situation. It doesn't make sense to provide help to a UI page by giving the image of that very UI page.
When you put it like that, I think I have to agree to you.
And the other reason is the translation cost. We translate our online help or user guide, whatever you call it. And when we insert an image, we have to pay for its translation too.
And, we need to understand that the user of our products is not really a novice user. Even if our users have not used our product earlier, they would still not require screenshots to perform tasks. In fact, users would rather want to know where to go next after completing this task. Or where am I, at what step am I in the entire process? These workflows will answer those questions.
With the new guide, can we test whether we have a good flow? What I mean is, I am now leaning towards a guide where there are no screenshots but I would still like to test that. Once we are ready with the refactored guide, can we test it?
Absolutely! We'll certainly do that. I'll ask someone from my team who hasn't worked on this product to do the end-to-end testing of the document.
Sounds good. Thanks, Ajay. And thanks Manasi for the refactoring. I think the guide will be in a good shape now.
Thanks much, Alfred.
Alfred, I'll work with you separately for the testing plan. Maybe we can involve QA in that too.
Thanks, Ajay. Sounds like a great plan.
Alright, talk to you later, Alfred. Thanks.
Whew! Finally he agreed!
Yes, he did. And we had to show him how screenshots wouldn't help at all. You know what, I am now wondering who the real user in this was.
We kept on discussing novice users and experienced users. But we really had to handle a user who knows the product in and out, who also knows the documentation, and wants enhancements and features in the documentation.
True. We were like customer representatives, selling our product, 'the refactored guide'.
Yes, what we learn from this is that our users will keep changing. Our internal teams become our users sometimes.
Sometimes it's the support or services people that we cater to.
That is correct. We ought to analyse our users when we sell our docs. Apart from the customer users, we also have internal users.
But anyway, good work at the end of the day. And mind you, when you keep the user happy, you keep the company happy!
With a hearty laugh, both exit.
Suyog Ketkar explains the basics of information design in This side up!
The cartoon faces are from http://www.makebeliefscomix.com/.