Go Premium for a chance to win a PS4. Enter to Win

x

Technical Writing

276

Solutions

253

Contributors

Technical writing is any written form of writing or drafting technical communication used in a variety of technical and occupational fields, such as computer hardware and software, engineering, chemistry, aeronautics, robotics, finance, consumer electronics, and biotechnology. IT encompasses the largest sub-field within technical communication. The Society for Technical Communication defines technical communication as any form of communication that exhibits one or more of the following characteristics: "(1) communicating about technical or specialized topics, such as computer applications, medical procedures, or environmental regulations; (2) communicating through technology, such as web pages, help files, or social media sites; or (3) providing instructions about how to do something, regardless of the task's technical nature".

Share tech news, updates, or what's on your mind.

Sign up to Post

Hi,

When we add a new feature to our web application, I insert a "NEW FEATURE" banner into the appropriate page. e.g.

NEW FEATURE: The system now supports reciting pi out to 20 decimal places. Click here for details.

I'm now documenting a change to existing functionality and want to announce this update in a similar manner. But, it's not a new feature. What would be a viable alternate term? ENHANCEMENT? SOFTWARE CHANGE? <Something else?>

Thanks,
Steve
0
Technology Partners: We Want Your Opinion!
Technology Partners: We Want Your Opinion!

We value your feedback.

Take our survey and automatically be enter to win anyone of the following:
Yeti Cooler, Amazon eGift Card, and Movie eGift Card!

Hi,

Of the two options below, which is preferable?

  1. Page-level settings
  2. Page level settings.

I'm leaning toward #1 but could be convinced otherwise. :)

Thanks,
Steve
0
Hi,

I'm blanking out here on proper terminology. Suppose I have an array (e.g. of seasonal records for a sports team).

2016: Wins: 8. Losses; 2.  Percentage: 80.00
2017: Wins: 4: Losses: 6.  Percentage: 40.00

The dataset also contains a totals object:
Wins:  12: Losses: 8. Percentage: 60.00

Wins &  Losses are the SUM of the individual elements. But, what's the term for the Percentage (60.00). Aggregate?

Need the above for an API guide.
Thanks,
Steve
0
Hi,
I'm writing an API guide for an application that accepts input - and generates output - in JSON format.

Suppose I have the following (redacted) code:
{
   SSN :  "012-34-5678",
   DOB: "1986-10-27",
   Age: 30,
   name: {
      first: "Daffy",
      last : "Duck"
    },
   Department: "Sales"
}

Open in new window


1. Is this entire entity referred to as a block or object?
2. Same for the name element, which contains first/last name.

Also, is JSON syntax considered closer to Java? Or to JavaScript?  The reason I need to know the latter is that I'm showing code samples in Confluence. While Confluence has a Code Block Macro, it does not come with prepackaged JSON formatting.

Thanks,
Steve
0
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
0
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.
0
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?)
 Example3. To filter by distance...
etc.

How would you fill in the blank in step 2?
Thanks.
0
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:
highlight tool
But, I don't see it on the toolbar at top of the screen:
Whrere's the highlighting button
Please advise as to where I can find it. Thanks!
Steve
0
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
0
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.Example of table
0
Keep up with what's happening at Experts Exchange!
LVL 11
Keep up with what's happening at Experts Exchange!

Sign up to receive Decoded, a new monthly digest with product updates, feature release info, continuing education opportunities, and more.

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
0
I need to know how to wire internal wiring
0
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.
Boxed Field Names
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
0
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.)
SnagIt Checkered Background
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
0
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.
1
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!
0
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
0
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. :)
0
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
0
Free Tool: Subnet Calculator
LVL 11
Free Tool: Subnet Calculator

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.

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
0
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
0
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
0
Hello,

I'm documenting a report that includes a dropdown menu for date selection. e.g.

Today
This Week
This Month
This Year
Custom Date Range


Is it correct to say:
Select your Date Range from the dropdown menu?

I ask b/c to me, a Date RANGE is when you specify a starting and ending date (e.g. 5/10/2017 to 5/16/2017).

If "Date Range" is not appropriate,what would be?

Thanks,
Steve
0
For years, I was taught, I saw and I wrote that the area in the lower right corner of the Windows UI was the System Tray or Systray.
I just looked at the Microsoft Manual of Style 4th Ed and it's now called the Notification area.  
Where can I file formal complaint?  This is a stupid change.

Ugggh.
1
Hello,

I'm documenting a web application where the only way to exist is to exit the active browser window (tab?) in which the app is running.

Which is better terminology?

"To exit this application, close the active browser window"
"To exit this application, close the active browser tab""
<Something else>?

However I state it, I want to make it clear that you should not close the entire browser. :)

Thanks,
Steve
0

Technical Writing

276

Solutions

253

Contributors

Technical writing is any written form of writing or drafting technical communication used in a variety of technical and occupational fields, such as computer hardware and software, engineering, chemistry, aeronautics, robotics, finance, consumer electronics, and biotechnology. IT encompasses the largest sub-field within technical communication. The Society for Technical Communication defines technical communication as any form of communication that exhibits one or more of the following characteristics: "(1) communicating about technical or specialized topics, such as computer applications, medical procedures, or environmental regulations; (2) communicating through technology, such as web pages, help files, or social media sites; or (3) providing instructions about how to do something, regardless of the task's technical nature".