Technical Writing

280

Solutions

255

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

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.
0
Free Tool: Path Explorer
LVL 11
Free Tool: Path Explorer

An intuitive utility to help find the CSS path to UI elements on a webpage. These paths are used frequently in a variety of front-end development and QA automation tasks.

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

Hi,

From what I know, if you are documenting a data structure (e.g. JSON) with embedded objects, you might have something like this for the data schema tables:

DISCLAIMER: In the real world, I doubt you'd have a full (e.g.) doctor object embedded in the prescription object. More likely, you'd have a record number for patient, doctor, drug, but the below is useful for this example. :)

PRESCRIPTION OBJECT
Date
Time
Rx Number
Patient Object
Doctor Object
Drug Object
Directions
etc.


You'd then have tables for the aforementioned objects, which themselves could contain objects:
DOCTOR OBJECT
LastName
FirstName
IdNumbers Object
Address
etc.

And in turn...
ID NUMBERS OBJECT
Licence
DEA
NPI
-----------
Now, to the question. I'm documenting an API where some of the embedded objects contain only one field/object. To use the above example, something like:

PRESCRIPTION OBJECT (as before: contains many fields/objects)

DOCTOR OBJECT (Contains one object)
IdNumbers Object

ID NUMBERS OBJECT (Contains one field)
License

Per the above, would I be overdoing it to have separate data tables for these objects containing only one field/object? If so, I'd need to find a clean way to embed everything in the parent table.

Thanks!
Steve
0
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
What are the rules/guidelines regarding the use of "You",  "I" and other pronouns in writing user manuals and other documentation.
Are there any specific rules for tutorial scripts which will be used by on-screen narrators/talent or tutorial voice over talent?
0
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
How to Use the Help Bell
LVL 11
How to Use the Help Bell

Need to boost the visibility of your question for solutions? Use the Experts Exchange Help Bell to confirm priority levels and contact subject-matter experts for question attention.  Check out this how-to article for more information.

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
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
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. :)
0
short.PNGShort sentences draw the eye amidst consistent scrolling. Give your posts a short one-liner to truly increase engagement in our community!
2
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
Free Tool: Port Scanner
LVL 11
Free Tool: Port Scanner

Check which ports are open to the outside world. Helps make sure that your firewall rules are working as intended.

One of a set of tools we are providing to everyone as a way of saying thank you for being a part of the community.

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
get-to-the-point.PNGSay what you need to and nothing more. Increase engagement with concise posts!
3
0
 
LVL 66

Expert Comment

by:Jim Horn
Vivacious verbs?  So are we selling real estate now at the expense of technical content?
0
 
LVL 11

Author Comment

by:Experts Exchange
Of course not, just sharing overall tips in this article.
0
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
ask-a-question2.PNGThe 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.
3
 
LVL 7

Expert Comment

by:Craig Kehler
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.
1
 
LVL 66

Expert Comment

by:Jim Horn
(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.
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

Technical Writing

280

Solutions

255

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".