Technical Writing Help

Hi,

The question below was generated by needing to document a JSON structure, but I suppose it could apply to other data formats as well.

Suppose I have a structure:
{
name: "John Doe",
address: "1234 Main Street",
vitals: {
hair_color: "brown",
eyes: "blue",
},
DOB: "01-01-2000",
sex: "Male"
}

Normally, I'd create a table with one row per data element. But, then I have the vitals block, which contains two data elements. Should I create a separate table for vitals, even though it contains only two fields? And reference it in the main table?

Thanks,
Steve

12 Comments

LVL 4

Question by

Stephen Kairys

1d agoSolved

SnagIt - How to close image file in editor

Hi,

After I finish editing an image, I would like to close the file so it's no longer in the editor the next time I invoke it. However, the FILE menu does not contain a CLOSE choice. How, then can I accomplish what I need?

Thanks.

6 Comments

Hi,

What is the correct/accepted terminology for a small portion of a screen that does not necessarily contain a data field?
Here's an example from a public website (not from my client work).

1. Click 'Races'.
2. You will see the following: ___________________. (segment? display? snippet?)

3. To filter by distance...
etc.

How would you fill in the blank in step 2?
Thanks.

6 Comments

LVL 4

Question by

Stephen Kairys

7d agoSolved

Snagit Editor - Where is highlighting tool?

Hi,

I need to highlight a small portion of an existing screen capture. According to the SnagIt documentation:

https://support.techsmith.com/hc/en-us/articles/215174508-Highlighter

I'm supposed to click on the highlighter tool:

But, I don't see it on the toolbar at top of the screen:

Please advise as to where I can find it. Thanks!
Steve

7 Comments

LVL 4

Question by

Stephen Kairys

2017-10-03Solved

Tech Writing- Is the phrase 'must always' redundant?

Hey everyone,

The grammarian in me is wondering the following (in the interest in saving words):

If I wrote:
You must always enter at least one vendor phone number.

I'm thinking the adverb "always" is not needed, since "must" by itself means 100% of the time. Along the lines of "The noise stopped completely" does not need "completely".

Agree? Disagree?

Thanks always! :)
Steve

Technical Writing

4 Comments

LVL 4

Question by

Stephen Kairys

2017-09-28Solved

Tech Writing- Numbered list in API doc

Hello,

In an API doc, I have a table describing data fields in a database

My question: If there is only one item, is it considered okay not to number it. I ask b/c of the last two field (Department and Employee Type). I don't think I need to number this item b/c they contain an ordered list. Scrubbed example follows.

Thanks.

17 Comments

LVL 4

Question by

Stephen Kairys

2017-08-30Solved

Tech Writing - Drop-down menu vs. Drop-down list?

Hi,

To me, a drop-down menu is a list of choices/actions e.g.
- All Accounts
- Internal Accounts
- External Accounts

or

- Patients
- Doctors
- Drugs

However, I sometimes need to document the case where you type in a partial key and then choose from a list of matches. e.g
I type "apple" and see
- Applesauce
- Apple pie
- Apple (red delicious)

To me, the above is not a menu, but a list. Accordingly, would it be kosher to refer to the above as a "drop-down list"?

Thanks,
Steve

Technical Writing

3 Comments

Question by

Rick Griffin

2017-08-29Solved

Samsung 12c-CC'd video camera wiring

I need to know how to wire internal wiring

Technical Writing

3 Comments

Hi,

In the fictitious screenshot below, (which contains only two fields, but my live screenshot for customers has six), and each option is more complex than my example.

I enclosed the field names in black boxes to make them stand out. Accordingly, I wrote:
"This option consists of six settings, boxed in the above screenshot."

But, is "boxed" the correct word here?

Thanks,
Steve

5 Comments

Hi, I have a digital art project I'm currently a part of, and I really need a long line with no gaps. As you can see below, there are gaps in between every em dash I put. ↓↓↓

————————————————

It is also important to note that I am doing this project on my phone; therefore, solutions available for Android phones will be highly appreciated.

Please reply soon, because the due date for this project is close. Thank you. :)

7 Comments

LVL 10

Post by

Experts Exchange

2017-08-02

Short sentences draw the eye amidst consistent scrolling. Give your posts a short one-liner to truly increase engagement in our community!

0 Comments

Add Comment

SnagIt 13.1.1 (32 bit)/Win10:

In a screenshot, the empty space on the right of a screenshot has this checkered pattern. (Please see example below.) I recall an option that allows me to change to all white, but can't find it.

(In this example, I've scrubbed the content to the left of the border.)

Accordingly.
1. How do I change to all-white?
2. How can I set the default to all-white so I don't have to change it every time?

Thanks,
Steve

4 Comments

LVL 7

Question by

Brian Matis

2017-07-25Solved

Favorite way to make an em-dash?

Quick, for those of you that care about copywriting, typography, and such: what's your favorite way to make an em-dash (—)? My current method is to do a Google search and copy/paste, but this seems terrible and I feel bad every time I do it because I know there are more efficient ways. I've been too ~~lazy~~ busy to train myself to do something better, but maybe learning your favorite way(s) will finally prompt me to take a more efficient approach...

Note: most of my writing is done in a web browser and I tend to bounce between Chrome on a PC and Safari on a Mac.

13 Comments

LVL 10

Post by

Experts Exchange

2017-07-25

Say what you need to and nothing more. Increase engagement with concise posts!

0 Comments

Add Comment

LVL 10

Post by

Experts Exchange

2017-07-20Edited

Elicit appeal with vivacious verbs! Daring diction and beginning posts with a verb or visually appealing language is the crux to increasing engagement.

8 Ways to Write an Engaging PostLast month, we released our new feature, called Post. This new product was created to expand our community-driven platform and personalize experiences on our site through topical conversations....

2 Comments

LVL 66

Expert Comment

by:Jim Horn2017-07-20

Vivacious verbs? So are we selling real estate now at the expense of technical content?

LVL 10

Author Comment

by:Experts Exchange2017-07-20

Of course not, just sharing overall tips in this article.

Add Comment

Hi,

Maybe I'm quibbling here...

But, which of the two options below is correct:
1. Click here for the customer-facing documentation on the public Wiki.
2. Click here for the customer-facing documentation in the public Wiki.

Thanks!

5 Comments

LVL 10

Post by

Experts Exchange

2017-07-10Edited

The best part about utilizing a technology community is the endless amount of opinions available to you. Try polling our community in a Post to see how interested others are in what you are passionate about.

6 Comments

load previous comments (4)

LVL 6

Expert Comment

by:Craig Kehler2017-07-12

Hey Jim on the off topic concerns, we are seeing an increase in traffic overall based on our efforts. See more information here
http://blog.experts-exchange.com/ee-blog/community-update/

I looked at the stats for the My SQL Server topic and the questions asked, excluding deleted, were up year over year for April and May but saw a decline in June. I'll see if I can find further indications why this is the case.

One thing I use that you may find useful is Google Trends. It can help you see how in general search terms are trending.

https://trends.google.com/trends/explore?date=2015-06-12%202017-07-12&q=%2Fm%2F0120vr

We are very interested in the health of topics, feel free to message me if you have some further insights or concerns.

LVL 66

Expert Comment

by:Jim Horn2017-07-12

(reading for the first time) Nice article. Gotta like that action. I suppose it's difficult to interpret results and do a cause-and-effect to what EE initiative led to the increase(s) in volume.

It was very unexpected when Gene agreed to sponsor my SQL Saturday last year, to include free memberships, and was disappointed when that didn't translate to signups. Perhaps I need to rattle a few cages in my local SQL community.

One thing I never really understood (keep in mind I'm not an SEO guy) is why tags were discontinued from articles in place of the question title. Last year I tried doing a Google search for keywords that should have resulted in my articles in the search results (SQL Server GROUP BY, SQL Server CASE, etc.) and results were not that hot.

For some reason my two Requirements Document Template articles get significantly higher views then the other articles. Maybe I just nailed the title correctly. A Google search for 'requirement document template reporting' shows my article as #2.

Add Comment

LVL 4

Question by

Stephen Kairys

2017-07-07Solved

Tech Writing - Instruction set with only one step

Hi,

Maybe I'm overthinking this one...

When I write an instruction set, my format is along these lines (made-up example), oversimplified:

To create an EE post:
1. Clock Ask a Question.
2. Fill in your title.
3. Select topics.
4. Write your post.
5. Click Submit.

But, what if there's only one step e.g.
To exit the application:
1. Click Logout.

Is my instinct correct that I'd be better off without numbering the single step:
To exit the application: click Logout.

Thanks,
Steve

Technical Writing

2 Comments

LVL 10

Post by

Experts Exchange

2017-07-07Edited

We love reading about your technical experience and expertise. However, this community allows you to post about topics related to your everyday life as well. Bee bold with your posts!

3 Comments

load previous comments (1)

LVL 123

Expert Comment

by:Andrew Hancock (VMware vExpert / EE MVE^2)2017-07-07

and I've got plenty of Bee - photos!

LVL 18

Expert Comment

by:Lucas Bishop2017-07-07

I don't get what all the buzz is about?

Add Comment

Free Tool: Subnet Calculator

LVL 10

The subnet calculator helps you design networks by taking an IP address and network mask and returning information such as network, broadcast address, and host range.

One of a set of tools we're offering as a way of saying thank you for being a part of the community.

Hi,

My document suite for a web app contains a HELPFUL HINTS doc, which provides general info about the application.

I need to list certain system requirements/restrictions. Right now, I have only one (min. browser width), but this list could grow over time.

What's the best title for this section?
System Requirements (As I said in the title.)
Limitations (Meh.)
???

Thanks,
Steve

PS-Hope I'm not overthinking here...I think part of my brain's still on the holiday weekend. :)

2 Comments

LVL 4

Question by

Stephen Kairys

2017-06-14Solved

SnagIt - Add Text Box (with border) plus arrow

Hi,

I'm getting up to speed with using SnagIt for screen captures. I'm trying to add a text box with an arrow pointing to a component of the screenshot.

While I can type text into a whitespace area of the screenshot, it displays w/o a border. So, I need to figure out how to add the border. If SnagIt could do it automatically, like MS Word does for text boxes, that would be great. In addition, what's the best way to add a red arrow?

Thanks,
Steve

14 Comments

Question by

Martin Gerlach

2017-06-09

IT Project Proposal Resource

I am looking for some kind of website where I can find sample proposals for different kind of IT projects? I know I can deliver the technology to my clients but I can't write a decent proposal which probably caused me to loose several bids. I right for example I am writing one for a VDI solution for a school. Does anyone know any resources?

Thank you!

Martin

1 Comment

Hello,

In a web application, we have a horizontal area of the screen displaying various metrics. e.g. (scrubbed)

Temperature Humidity Wind Direction Wind Speed Barometer
74 53% SW 10 MPH 29.86

It's not a toolbar or ribbon b/c it's display-only. Accordingly, is there a more concise name than "screen area"? I suppose I could say "section", but I'm not thrilled with that word. :)

Thanks,
Steve

5 Comments

Hi,

I'm documenting a time field that displays (e.g) 10;42:38.496
where .496 is 496 thousandths of a second.

So, if I say
HH:MM:SS.xxx, which are the letters to use for xxx?

Thanks,
Steve

6 Comments

Hello,

What is the proper terminology for a horizontal area at the top of a screen that contains not only menu choices, but also other options (e.g. change password, configure screen layout, etc.) I can't truly call it a menu, so what works? Panel? Bar? Something else?

Unfortunately, I cannot provide a screenshot b/c the software's proprietary.

Thanks,
Steve

10 Comments

COURSE of the MONTH

Technical Writing

Related Topics

Technical Writing

Related Topics