Tech Writing - Need Another Pair of Eyes

Hey everyone,

Trying to figure out if something I wrote would be clear to someone familiar with data concepts such as fields, columns, rows, etc.

In this scrubbed example, the data consists of Widgets, each of which belong to a Widget Group.  One of the columns is "Type" (e.g. Utensil, Appliance, etc.)  A report exists that has one row per group, with its widgets below it, if you choose to expand the row with the group. Some report columns (e.g. Type, Manufacturer, etc.) apply to both groups and widgets.

I describe the Type column as follows:
"For widget groups: various if Types differ. Otherwise, the uniform Type displays.

How would you interpret the meaning of "The uniform type displays"?  I want to be sure the reader will understand my intent. :)

Thanks.
LVL 4
Stephen KairysTechnical Writer - ConsultantAsked:
Who is Participating?

[Product update] Infrastructure Analysis Tool is now available with Business Accounts.Learn More

x
I wear a lot of hats...

"The solutions and answers provided on Experts Exchange have been extremely helpful to me over the last few years. I wear a lot of hats - Developer, Database Administrator, Help Desk, etc., so I know a lot of things but not a lot about one thing. Experts Exchange gives me answers from people who do know a lot about one thing, in a easy to use platform." -Todd S.

Joe Winograd, Fellow&MVEDeveloperCommented:
Hi Steve,
This just hit my inbox. I should be able to look at it in less than an hour. Regards, Joe
0
Stephen KairysTechnical Writer - ConsultantAuthor Commented:
Thank you.
0
JohnBusiness Consultant (Owner)Commented:
If there were different types, the Widget groups displays various
Otherwise uniform  is shown.
0
OWASP: Avoiding Hacker Tricks

Learn to build secure applications from the mindset of the hacker and avoid being exploited.

Stephen KairysTechnical Writer - ConsultantAuthor Commented:
John, is that how you interpreted what I wrote? That there's a value called "uniform"? Thanks.
0
JohnBusiness Consultant (Owner)Commented:
That is what "The uniform type displays" means to me as I read it.
0
Stephen KairysTechnical Writer - ConsultantAuthor Commented:
OK, glad I asked. :) What I meant was that  (e.g) if all widgets had type "appliance", then "appliance" displays.
So...how to reword....

How about:
"For widget groups: various if Types differ. Otherwise, the Type in common displays.
0
JohnBusiness Consultant (Owner)Commented:
Try this:

"For widget groups: various if Types differ. Otherwise, the Actual Type in common displays"
0

Experts Exchange Solution brought to you by

Your issues matter to us.

Facing a tech roadblock? Get the help and guidance you need from experienced professionals who care. Ask your question anytime, anywhere, with no hassle.

Start your 7-day free trial
Stephen KairysTechnical Writer - ConsultantAuthor Commented:
@John,
Sounds a bit better. But, curious. What about the word "Actual" do you think clarifies the sentence? Thanks.
0
JohnBusiness Consultant (Owner)Commented:
Actual Type (or Named Type maybe) does clarify the sentence.
0
Stephen KairysTechnical Writer - ConsultantAuthor Commented:
I like "Actual".

Good to know that my initial attempt ("in common") was OK after all. I had changed it to "uniform" at someone's suggestion, but glad I had that sliver of doubt... :)
0
Stephen KairysTechnical Writer - ConsultantAuthor Commented:
Thank you, John! Now, I can sleep more easily. :)

Have a good evening.

@Joe - No need for you to respond, as  I need to move onto the next item but thanks for wanting to help.
0
JohnBusiness Consultant (Owner)Commented:
Thank you and I was happy to help.
0
Joe Winograd, Fellow&MVEDeveloperCommented:
> "For widget groups: various if Types differ. Otherwise, the uniform Type displays.

I understand data concepts such as fields, columns, rows, etc. very well, but the language above is not clear, imo. I think you're trying to be too concise in the language. I think you'll need to be more verbose to get the concept across clearly. Regards, Joe
0
Stephen KairysTechnical Writer - ConsultantAuthor Commented:
Well, hear this. I just looked at the doc for a similar report and found the following, which I think works:

"Displays the type if it's the same for all widgets. Otherwise, displays "multiple".

OMG, i would have saved all of us a lot of effort had I honed in on that two hours ago... :)

Thanks.
0
Joe Winograd, Fellow&MVEDeveloperCommented:
Oops...when I hit the submit button, I see that a lot has happened and you already accepted an answer. Fair enough. I just reviewed the thread and, imho, the Accepted Solution is no better than your original language — it is also too brief and I doubt that most readers will understand your intent. Regards, Joe
0
Stephen KairysTechnical Writer - ConsultantAuthor Commented:
So, then, how about my last comment?
0
Stephen KairysTechnical Writer - ConsultantAuthor Commented:
@Joe, is this clearer do you think?

Displays the type if it's the same for all widgets. Otherwise, displays "multiple".
0
JohnBusiness Consultant (Owner)Commented:
The above could work as well. I tried to adapt your first sentence, but the last one works also.
1
Stephen KairysTechnical Writer - ConsultantAuthor Commented:
Thanks. My final take on this is that I was looking at it the wrong way. Mentioning the "individual" case first made life so much easier.

Lesson learned for me: Don't reinvent the wheel if it's already accumulated useful mileage.. :)
0
Joe Winograd, Fellow&MVEDeveloperCommented:
That's clear for Widgets, but not clear for Widget Groups, imo.
0
Stephen KairysTechnical Writer - ConsultantAuthor Commented:
>>That's clear for Widgets, but not clear for Widget Groups, imo.

Which part do you have in mind per Groups?

>>Displays the type if it's the same for all widgets. Otherwise, displays "multiple".
0
Joe Winograd, Fellow&MVEDeveloperCommented:
I think the real lesson learned is that you're trying to make it too brief...too concise...too simple. Reminds me of that famous supposed-Einstein quote:
Everything should be made as simple as possible, but no simpler.
Regards, Joe
0
Stephen KairysTechnical Writer - ConsultantAuthor Commented:
LOL!
OK, but to get specific. Were you saying that "Otherwise, displays multiple" was the unclear portion?

So, how about this:
If the type is the same for all widgets (e.g. "Appliance"), it is displayed here. Otherwise, "multiple" is displayed.
0
Joe Winograd, Fellow&MVEDeveloperCommented:
> Which part do you have in mind per Groups?

Problem is, the Type column can apply to both Groups and Widgets. So when you say...
Displays the type if it's the same for all widgets. Otherwise, displays "multiple".
...does that mean the "Otherwise" applies to Groups only, not Widgets?
0
Joe Winograd, Fellow&MVEDeveloperCommented:
Our messages crossed, but, yes, "Otherwise, displays multiple" is unclear. Does that refer to Groups only, not Widgets?
0
Stephen KairysTechnical Writer - ConsultantAuthor Commented:
OK, this was a bit out of context. I may've overscrubbed it. :)

Think of the below as one bullet point in a list of apx. 10 fields:
 Widgets

Does the above look any better, now that you see the context? (It's a screenshot b/c I'm not sure if EE supports two-level bulleted lists. :) )

Thanks.
0
Joe Winograd, Fellow&MVEDeveloperCommented:
Yes, that's better, although I don't know where "ad tags" came from. :)

EE supports multi-level bullets. Click the Indent tool, then the Bullet tool for higher (or is that lower?) levels:

  • This is level 1
  • Level 2
  • Level 2 again
  • Level 3
  • Back to 2
  • Back to 1

Make sure the BBCode has list=circle to keep the circles — unfortunately, the default for higher levels is list=1, which creates numbers instead of circles. Regards, Joe
0
Stephen KairysTechnical Writer - ConsultantAuthor Commented:
Yeah, I forgot to scrub "ad tags".  Guess it's time to shut down for the day.
But, fixed it in the screenshot now posted. Our posts must've crossed again. :)

Thank,s Joe.
0
Stephen KairysTechnical Writer - ConsultantAuthor Commented:
Hey everyone,

Just after I awakened, I realized a solution to my original sentence structure, which refers to "if they differ" first.

>>"For widget groups: "various" if Types differ. Otherwise, the Actual Type in common displays"

Of course, I should have said something like:

For widget groups: If the types differ, the column displays "various". Otherwise, it displays the Type they have in common.

More conversational than the original attempt, which confirms your (Joe's) comment about being too concise. I have to laugh b/c when I'm writing my novel, I'm usually writing "normal" sentences like the above. (There are exceptions, including in conversation, but I won't go there now. :) ),

Lesson#2 learned: When I'm spending so much time on the wording for one sentence, time to put it aside for a while. I love how the better phrasing occurred when I was off the grid.

Thanks again.
1
Joe Winograd, Fellow&MVEDeveloperCommented:
> For widget groups: If the types differ, the column displays "various". Otherwise, it displays the Type they have in common.

There ya go! Very nice!

> More conversational than the original attempt

Yes, and that's the ticket, imo.

> time to put it aside for a while

The old "sleep on it" trick. :)
1
Stephen KairysTechnical Writer - ConsultantAuthor Commented:
Exactly. Conversational can be good, but not overdoing like this one:

"Otherwise, it displays the Type they have in common, shimmering on the computer screen like the moon on the nighttime lake. :)"
0
Joe Winograd, Fellow&MVEDeveloperCommented:
hehe...good one.
0
It's more than this solution.Get answers and train to solve all your tech problems - anytime, anywhere.Try it for free Edge Out The Competitionfor your dream job with proven skills and certifications.Get started today Stand Outas the employee with proven skills.Start learning today for free Move Your Career Forwardwith certification training in the latest technologies.Start your trial today
Technical Writing

From novice to tech pro — start learning today.