My Technical Writing Process // Step 1: User-testing the application


Today I am starting my documentation
process for the Cover Letter Snippets application. This is the open source
project that I chose to write documentation for and also record my
writing process and the first step of my writing process is user testing the
application so that’s what I’m doing today I am going to think out loud as I
test the application and I am also going to note my observations in a Google
document. So the first sentence of the application web page is that it’s an
angular MongoDB NodeJS Express local application. So the start of with the
tech stack which makes sense if the audience is the recruiters – like, if the creator of this product is applying for jobs and they want to present this
project as an example of their technical skills then it makes perfect sense to
start with this with the tech stack for this. But if the audience is end user so
it might not make sense to start with the tech stack. So I’m going to make a note of
it. Starting off with a tech stack – yes if the audience is recruiters might want to change it if the
audience’s non-developers. Okay, moving on local application for quickly composing
a cover letter that discusses each keyword and technology on the job
listing. I have a problem with the word “quickly” here because it kind of sets an
expectation of how the user should be able to use it. Like if you’re not able
to do it quickly then you’re not good enough to use this application but it
adds an expectation for the users technical expertise without adding any
value to the sentence so I’m just going to take it out. So I’m going to make a
note of it. Okay moving on – quickly composing a cover
letter that discusses each keyword and technology on a job listing – this is not
technically correct. We are not discussing each keyword and technology
on a job listing; we are choosing the ones we want to discuss. So let’s make a
note of that – Remove “each” from the sentence. Okay,
let’s go down to the actual Readme. Okay let’s just scroll down and see how what
we are working with. I love the screenshots – it shows that they have put in a lot of efforts and they really
care about good documentation and I’m very impressed with it. They also have
good headings and subheadings so it’s easy and scannable. Let’s make a note of
that too. Okay, so first sentence is the same… the
seconds once you can use this tool to figure out what keywords appear most
frequently in the job description and quickly add paragraphs from your
previous cover letters and discuss those important keywords. So the two benefits
of this tool are that you can analyze the keywords in a job description and
you can reuse content from your existing cover letters. So let’s make a note of
that Okay let’s scroll down to the actual
installation instructions – using snippets to install snippets run this command
there’s an additional or optional command and then to run the snippets
enter the command snippets to run the program this will start a local host
server that will serve the application on this localhost and the browser will
open automatically. I think we can simplify this instructions – like, make the
more scannable and just simply pattern so let’s make a note of that we also don’t know these are
instructions are applicable to all operating systems – like will this work on
Windows I don’t know. I need to check okay now let’s actually try running
these instructions oh the installation was so fast.. hmm
..let’s run it Yay! It worked!
let me bring this to this browser okay so use a JSON file and connect to
your database. So I can use a JSON file and connect to my database? what? let’s
see what to Readme says. The easiest way to save your cover letter snippets is to
store them in a JSON file.. okay that’s the JSON file. And you can click
connect and create a file you can do it from and write – okay and you can also
use an Mlab database which i think is a MongoDB database. There is also then
existing database that you can use to try out the application. That’s cool.
That’s a good move like giving people something to play around with before
having to set up their own database. Nice I think we can simplify these options
like there are three options for the same task of connecting to a database we can use it locally on it using a JSON
file or you can connect to your MongoDB database or you can use the
existing MongoDB database. Okay setting up a database – Snippets uses
a MongoDB database on Mlab.com. To store your cover letter snippets data go
to the website and and create new under new deployment click
create new and our deployments choose you to do is pick a region follow the
prompts click on your new .. all of this is to set up a new database but as
we just saw that is just one of the options and I don’t think this is the
most user-friendly option like if if I were given a choice if I can do it
locally then I would just use a JSON file or I would use the trial database
that the creator has set up for me so setting up a database on MongoDB
feels like an advanced use case and I don’t know if that should be included
here.These steps are kind of breaking the flow so I think I’m just gonna have
a QuickStart setup without MongoDB and then an advanced setup with MongoDb okay moving on to adding snippets. Copy
paste a small snippet of a previous cover letter – okay so that’s a
requirement that I need to have a previous cover letter handy to add
snippets from the previous cover letter and we need to call out that requirement. without the categories meaning with the
keywords now it’s also important for you to add an intro and outro category let’s try this out – connect to JSON file it is an example snippet from the
new JSON file.. delete me.. create new ones .. okay okay says to
delete the first snippet so I’m going to do that. Now let’s add a snippet – include a
snippet from your cover letter that you feel is well articulated and communicate
experience well then fill out the category is that relates to this cover
letter. Okay..for now I’m just going to type in a paragraph about my experience
as a tech writer and not bother with opening my actual cover letter because I
don’t know where it is and I need to hunt it down and that’s not important right
now I just need to try out this application and I’m also going to put in keywords
that I know will show up in the job listings so that we can see if the
application picks those keywords and matches it to the job listing when we
add the job listing. Okay so I think I have enough keywords here: DigitalOcean
AWS GCP markdown github and Jekyll ..yeah okay so we added a snippet hmm now we need intro and outro snippets I’m just gonna put dummy text okay editing snippets – the database page
we should see a list of all snippets. Yes, our added snippers are here. Yay! Now we can
proceed to building a cover letter Awesome. So we need a job description. I’m
going to look up the technical writing job on the Cockroach Labs website and I’m
just going to copy paste our description that I know matches the keywords that
I’ve entered into the cover letter snippets app okay so I’ve added the job description
and I know that I use the keyword markdown so it should show up somewhere on
this page. Where do I see the snippets? Show intros..there are no intro snippets. Show
more.. oh there they are okay here are all the snippets that I’ve
added yeah I can see the markdown snippet nice and then I also have an
outro snippet..awesome but I don’t have an intro snippet. I do have an intro
snippet. Why wouldn’t this show up.. oh because the “I” is capital? Do you need that
to be small letters? Does that work? oh wow it showed up.. huh ..so the
categories are case-sensitive that is a very important find that we
need to make a note of another important point is start to edit
the text we need to click inside the box that is not very intuitive actually build a cover letter so let’s
select the markdown snippet.. add then let’s also have an intro snippet Where did my intro snippet go? What? Now let’s add an outro snippet. Why wouldn’t my intro snippet show up? what? I did add it.. I can see it here
why can’t I see it on the Build a cover letter page? hmm.. this is so strange.
Show intros.. what? Why isn’t the intro snippet showing up? I’m
just going to try adding a new one now this is an intro see if it shows up now.. it does! That is
so strange I don’t know it didn’t show up in the
first place but I’m glad it did now.. I’m just going to rearrange this thing and
yay! We have built our cover letter that is so awesome.
Woohoo! How do I export the cover letter though? Let’s see what the
Readme says about this. We did all of that export cover letter – you basically
done you can edit the text in the text area and can copy place your cover
letter into your word doc or PDF – so it does not really generate a word document
or a PDF you have to do that manually and that needs to be called out. Okay so
this is the end of the Readme which means this is the end of the user test.
We went through all the four steps of creating a cover letter and we also took
detailed notes about what we want to include in our new Readme. I think
this was a very successful user testing session and I’m pretty happy with it. In
the next session, we will write the actual Readme. I’ll see you then. Bye!

5 thoughts on “My Technical Writing Process // Step 1: User-testing the application

  1. Phase 1 of open-sourcing my technical writing process: User-testing the project. I used the "think-out-loud" method in this video – this is the method I had my undergraduate engineering students use when I worked as a Teaching Assistant at MS&T. I hope this video helps demonstrate how to use the method in the field.

  2. Hi Amruta i am also a Technical Writer wanted to make a career in to this field..so i have lot of questions regarding to this fields..

Leave a Reply

Your email address will not be published. Required fields are marked *