Brevity

  • (3 Pages)
  • +
  • 1
  • 2
  • 3

32 Replies - 1882 Views - Last Post: 29 July 2019 - 09:40 AM

#1 ArtificialSoldier   User is offline

  • D.I.C Lover
  • member icon

Reputation: 2355
  • View blog
  • Posts: 7,192
  • Joined: 15-January 14

Brevity

Posted 25 July 2019 - 10:06 AM

In my technical writing class that I took in college 20 years ago, the two lessons that have really stuck with me are to know your audience (don't explain anything they already know), and that the quality of your writing increases as you remove words without changing the meaning. One of our help desk guys has a major problem with this, and I'm looking for ways to help him. I'm almost positive he has one or more learning disabilities, but any suggestions will be helpful.

Here's an example of one of his bug tickets, names have been changed to protect the innocent:

Quote

On client.server.company.com if you log in as UGA Fname Lname and create a Learning Track and click save nothing happens the learning track doesn't appear on the screen, however, if you log out of her account and log in as a Main Admin and click on the learning tracks button in the navigation panel you can see the learning track Fname created. I checked Fname's permissions and she has the correct permissions to make learning tracks.

UGA Fname Lname should also have access to learning tracks that the Main Admin at Client made and she doesn't, she cannot see them.Please make it so that Fname can create a learning track and see it on her admin screen after she creates it.

I could not replicate this on Company University. Below are the steps to replicate the issue.

1. Log onto client.server.company.com as the main admin and do a UGA user search for Fname Lname.

2. Log in as UGA Fname Lname and click on the Learning Tracks button in the admin navigation panel.

3. Click the green cross that says "Add New Learning Track"

4. Create a random learning track and click save. You will notice after you click save the learning track doesn't appear on the screen it as if nothing happened.

Please fix this so Fname or any UGA can make learning tracks, Based on her permissions she should also be able to see the learning tracks that other Main Admins have made and she cannot. Please fix this.


This is what probably should have been submitted as a bug ticket:

Quote

UGA Fname Lname on client.server.company.com cannot see any learning tracks, even ones she creates.

Does anyone have any tips or resources I can use to help him? A fairly large part of my week is listening to him try to explain something while using about 20x the words that are necessary.

Is This A Good Question/Topic? 0
  • +

Replies To: Brevity

#2 modi123_1   User is offline

  • Suitor #2
  • member icon



Reputation: 15175
  • View blog
  • Posts: 60,742
  • Joined: 12-June 08

Re: Brevity

Posted 25 July 2019 - 10:12 AM

It may be that this is a benefit and not a detractor. I am on the flip side where bugs, errors, stories, etc all come in with extremely bare bones content, and most time require a large number of emails/calls to extract enough to start diagnosing the issue.

From my view having this fellow explain the steps they took, in the order they took them, is a positive. As is where they are _NOT_ seeing the issue, and other ancillary probing. (I am claiming 'Ancillary Probing' as my synth/pop retro wave band name.. no one take it!)
Was This Post Helpful? 1
  • +
  • -

#3 ArtificialSoldier   User is offline

  • D.I.C Lover
  • member icon

Reputation: 2355
  • View blog
  • Posts: 7,192
  • Joined: 15-January 14

Re: Brevity

Posted 25 July 2019 - 10:23 AM

It's definitely not a benefit. Another example of the problem is, maybe there's a user that can't see a certain piece of content that is assigned to them. This is the information I need:

1. The client
2. The user
3. The content
4. Why they should be able to see it (how was the content assigned to them?)

He'll often start in with something like the history of why they have their user groups set up a certain why, or how many people have called him about this, or how they feel about it, or any number of other extraneous details that don't help me do my job. When I try to interrupt and tell him to get to the point, he gets frustrated and it seems like he can't explain anything without starting at the beginning of whatever narrative the client gave him. He doesn't seem to be able to pull out only the details that are necessary to create a bug report.

This is from another one of his tickets:

Quote

If you make a classroom session and download the Student Roster CSV file and add students to the template and mark them as completed and attended on the template and then open the classroom session and upload the CSV template, the students do get added to roster which is great but they don't get marked as attended or completed.

That could have been this:

Quote

Uploading a roster to a classroom session does not mark students as completed or attended.


It may just be something I have to deal with, but I'm hoping someone has dealt with something similar.

If it matters, he's also the owner's son. Otherwise I would have suggested firing him a while ago, it can be very difficult to try to explain things to him. I'm trying to make the best of it.
Was This Post Helpful? 0
  • +
  • -

#4 astonecipher   User is offline

  • Senior Systems Engineer
  • member icon

Reputation: 2906
  • View blog
  • Posts: 11,328
  • Joined: 03-December 12

Re: Brevity

Posted 25 July 2019 - 10:29 AM

Then send him a template to follow stating exactly what you need.


I did chuckle at this,

Quote

I could not replicate this on Company University. Below are the steps to replicate the issue.

Was This Post Helpful? 0
  • +
  • -

#5 DarenR   User is offline

  • D.I.C Lover

Reputation: 625
  • View blog
  • Posts: 4,170
  • Joined: 12-January 10

Re: Brevity

Posted 25 July 2019 - 10:48 AM

i would have added the admin part also since that shows they tested it in other areas and didnt just say it's broken
Was This Post Helpful? 0
  • +
  • -

#6 ArtificialSoldier   User is offline

  • D.I.C Lover
  • member icon

Reputation: 2355
  • View blog
  • Posts: 7,192
  • Joined: 15-January 14

Re: Brevity

Posted 25 July 2019 - 10:55 AM

Quote

Then send him a template to follow stating exactly what you need.

I wonder if I can put a character limit on Jira...

Quote

Then send him a template to follow stating exactly what you need.

That might have to be it.
Was This Post Helpful? 0
  • +
  • -

#7 astonecipher   User is offline

  • Senior Systems Engineer
  • member icon

Reputation: 2906
  • View blog
  • Posts: 11,328
  • Joined: 03-December 12

Re: Brevity

Posted 25 July 2019 - 10:59 AM

I know you can do templates in Jira, previous company made it a requirement for business when they created a ticket it followed the specific template or it was rejected. Our bug tickets were done programmaticly so we could change the strings as needed. Had input controls of What, Where, Who, and we even added an upload for the windows psr so they could upload it if it was something we couldn't pin point.
Was This Post Helpful? 0
  • +
  • -

#8 NeoTifa   User is offline

  • NeoTifa Codebreaker, the Scourge of Devtester
  • member icon





Reputation: 4532
  • View blog
  • Posts: 19,148
  • Joined: 24-September 08

Re: Brevity

Posted 25 July 2019 - 12:26 PM

I used to do wordy defects like this, and the devs loved it. I know when trying to test other people's defects if they have the one liners it's extremely painful, and takes more time to hunt down more details as well as the test data that caused it. It's not just for you most likely. I don't know what you're not appreciative.
Was This Post Helpful? 2
  • +
  • -

#9 ArtificialSoldier   User is offline

  • D.I.C Lover
  • member icon

Reputation: 2355
  • View blog
  • Posts: 7,192
  • Joined: 15-January 14

Re: Brevity

Posted 25 July 2019 - 01:00 PM

These are submitted just for me. I appreciate having the detail that I need to do my job, I don't appreciate needing to sift through everything else to get that information. I don't need him to list everything that he's clicking on to get to a particular part of the application if that's the only way to get there for example, he can just tell me to go to that location. Unless the navigation process is part of the bug.

This is actually the result of him initially not giving enough information and me needing to pound it into his head that he needs to give me all of the information I need to see or replicate the problem, it's just gone too far the other way and he doesn't seem to understand the balance.

Like with the first ticket I quoted in the first post - in the title of that ticket that I didn't post, and several times in the description, he's talking about the different learning tracks that aren't appearing (learning tracks that she made, learning tracks the main admin made, etc). When I logged in to look into that and logged in as that user and clicked on Learning Tracks, there were none at all. It's not necessary to list all of the different kinds of learning tracks that aren't appearing - the problem is that the user is not seeing any of them at all.

I'm also the CTO, original designer, and for a couple years the only developer on this application, it's not necessary to list the steps to create a learning track. I know how to do that, I designed the interface and wrote the code. That goes back to knowing your audience, it's just more details that I don't need.

It sounds like I have a minority opinion on this though. I guess it's just a challenge working with people with learning disabilities, but that's not really news.
Was This Post Helpful? 0
  • +
  • -

#10 NeoTifa   User is offline

  • NeoTifa Codebreaker, the Scourge of Devtester
  • member icon





Reputation: 4532
  • View blog
  • Posts: 19,148
  • Joined: 24-September 08

Re: Brevity

Posted 25 July 2019 - 01:47 PM

I always lived by the code: write it so somebody off the street can do it. What if you get a new team member? What if it pops up in the future after you've left and they need to refer to the previous defect? What if business needs to look at it for metrics or whatever?
Was This Post Helpful? 1
  • +
  • -

#11 ArtificialSoldier   User is offline

  • D.I.C Lover
  • member icon

Reputation: 2355
  • View blog
  • Posts: 7,192
  • Joined: 15-January 14

Re: Brevity

Posted 25 July 2019 - 02:20 PM

Quote

What if you get a new team member?

My workload and stress level would go down dramatically. Those tickets are fine if people don't know the application, but he's writing tickets specifically for me.
Was This Post Helpful? 0
  • +
  • -

#12 macosxnerd101   User is offline

  • Games, Graphs, and Auctions
  • member icon




Reputation: 12634
  • View blog
  • Posts: 45,801
  • Joined: 27-December 08

Re: Brevity

Posted 25 July 2019 - 08:43 PM

It might be worth taking the time to teach him. There are a couple strategies that might be useful.
  • Set clear expectations. Model a couple of correct tickets, and explain why they meet your needs. Then emphasize why deviating from this model is bad. Tell him that fewer details impedes your ability to identify the issues, while the amount of information he has been providing causes you to spend an excessive amount of time trying to identify the issue.

  • Give him feedback on a couple of his tickets. Shred his writing, as if you were his technical writing or real analysis instructor. Tell him exactly what he is doing incorrectly and what needs to be fixed. My philosophy with grading work is to be a tough grader, and then be available to help students improve.


As you interact with him, it is important to make him feel like you are on his side. When students feel that there is an adversarial relationship with the instructor, they either dig their heels in or shut down. That isn't to suggest you are being adversarial.

Try to positively reinforce progress as well. A quick email "thanks for the concise ticket- I am looking into it now..." will likely go a long ways in developing a positive rapport and reinforcing the desired behavior.
Was This Post Helpful? 0
  • +
  • -

#13 jon.kiparsky   User is offline

  • Beginner
  • member icon


Reputation: 11604
  • View blog
  • Posts: 19,728
  • Joined: 19-March 11

Re: Brevity

Posted 25 July 2019 - 10:50 PM

Personally, if I had to choose, I'd ask people to overcommunicate by default. As you say, most people are not excellent writers, and I'd rather not have to go back for the details they left out, hoping to impress me with their style.
Was This Post Helpful? 0
  • +
  • -

#14 Skydiver   User is online

  • Code herder
  • member icon

Reputation: 6996
  • View blog
  • Posts: 23,774
  • Joined: 05-May 12

Re: Brevity

Posted 26 July 2019 - 07:16 AM

I prefer to see tickets/bug reports in the following format:

Title: 1 sentence that says what failed or what was expected behavior

Summary:
1 paragraph 3-8 sentences expanding on what failed or what was the expected behavior

Repro Steps:
0. Any initial setup or assumed configuration
1. Numbered steps describing
2. what got clicked on
3. or what inputs were provided

Results:
1-3 sentences describing what behavior was observed.

Expected Result:
1-3 sentences of what behavior was expected by the user.

Notes:
Multiple paragraphs which may explain further the expected behavior.
This may include background information justifying why the bug should be a high or low priority
and why it is high or low impact.
Was This Post Helpful? 0
  • +
  • -

#15 NeoTifa   User is offline

  • NeoTifa Codebreaker, the Scourge of Devtester
  • member icon





Reputation: 4532
  • View blog
  • Posts: 19,148
  • Joined: 24-September 08

Re: Brevity

Posted 26 July 2019 - 07:23 AM

This is my template:

Description:
 Environment (ST1, ST2, INET, etc.)?
 User ID?
 User Type?
 Browser/Device Type?
 Detailed Description of Issue/Error:

Steps to Recreate:

Expected Results:

Actual Results:

Workaround Description (non-Billing apps):


Was This Post Helpful? 0
  • +
  • -

  • (3 Pages)
  • +
  • 1
  • 2
  • 3