go to sections menu

The abc’s of technical writing, lesson 1 from blog The Technology blog and podcast

This is for the technology blog and podcast Commentary, articles, and podcasts

header picture for Ingegno theme

You are here: class assignments > The abc’s of technical writing, lesson 1

Go to Homepage, contents or to navigation menu



The abc’s of technical writing, lesson 1

Technical writing has changed through the years. Universal course has a course on technical writing, and it covers everything from podcasts, to screencasts and other aspects in the very first lesson. The first lesson of this class is asking to describe who would benefit from technical writing, and describe the people who may be in the field of technical writer. I linked to the sepdspace folder both in word, and here, for your convenience as you read the assignment. What else would a technical writer be doing do you think besides writing, podcasting, blogging, and the like? The assignment follows.


The assignment is asking to describe who may be responsible for doing technical writing. According to one paragraph, it says: ” Depending on a company’s size and needs, it may hire one or more full time technical writing specialists, or it may occasionally hire contract writers or outsource writing needs to freelance writers or agencies. In other cases, engineers, developers, project managers, and others involved in the creation of a product will be called upon to create user documentation and training materials for the product they are developing. If the term technical writing is defined a bit more broadly, it can include marketing and public relations materials, brochures, sales letters, and trade articles.”

Any particular profession such as hardware and software, hospitals, and other areas where information needs to be given to the public would be professions where technical writers would be needed. Programmers, engineers, and even the technical support specialists themselves may be called upon to write the documentation for the company, unless it gets outsourced to a company whose specialty is to do the work for you.

According to the lesson, technical writing does not mean writing anymore. It may include items such as screencasts, podcasts, and even blogging. I have done podcasts as a blind iphone user, learning software, and demonstrating it in understandable language. You are welcome to check out the sendspace folder where various pieces of software for the phone are demonstrated. Someone told me they liked the work I’ve done with these demos.

Since I have had to teach access technology, even old access technology from a young age, my communication in this field has been good, and I have been known to be patient with people who are new. I’ve tried to teach someone 70 years old how to use Windows, and as I mentioned on the forum, I have a text representation of a book I am willing to share upon request to show how i’ve done writing. I do know it has changed, and thats why I’m here. I’ve adapted to the podcast scene, ad i would do video if i had the right equipment and it was requested of me.


I hope you enjoy the class assignment, and I’ll post more if I feel it is good to share and bring up for discussion. Enjoy!


Informazioni sull'articolo

The abc’s of technical writing, lesson 1 was released on July 9, 2016 at 5:30 pm by tech in class assignments.
Last modified: July 9, 2016.


Comments (2)

  1. Comment by crashmaster date 9 July 2016 alle 21:41 (),

    Hi.
    O fuck man, so much to write about.
    Right, so thats all under technical writing.
    As I have understood it that traditionally has meant manuals or documentation.
    Podcasts can be dramas to tutorials to instructions, to reviews, to the sound of the toilet being flushed.
    So while a tutorial or review that advertises a program could be construde as technical writing, I’d hardly think a personal opinion is.
    Screencasts would be the same as casts though if they are tutorial related hmmm.
    Then we have unofficial casts.
    Blogs, um, I don’t know, all blogs are not surely technical writing.
    I wouldn’t class a blog as anything bar some wanker doodling on a diary.
    I don’t reguard my blogging as serious, I guess if it was about tech maybe but even then.
    Most people blog with opinions or their daily lives.
    Some blog about the state of their country or with their opinions about their government or so forth I find it hard to say blogs are technical writing.
    Forums are technical writing.
    Talking on skype is technical writing.
    facebook and twitter are technical writting its just to broad.
    I do think that technical writing should stay with program documentation and that be it or podcasts where instructional material is present.
    This could be part of blogs which contain articles and links to articles I guess as a stretch.
    And maybe forum/email posts to interest groups and twitter posts linking to such including but not limited to any article linking to other articles on the same or similar subjects.
    However as long as those didn’t change.
    How would you varify it may I ask you!
    How do you know if something you are reading is technical writing, a cast youtube video maybe but a blog or article?
    Sometimes I put my tech in amongst my other shit, I shudder to think that my weekly diaries or mindless rants on the fucked up state we live in could become formal writing.
    People get sued or put in jail for much less but even so.
    Half my blogs are status updates or my state of mind at the current time.
    It does not mean I will care about that a few weeks or even an hour later.
    will we be accountable to everything we do and have to class it?
    And if they are, then emails are technical writing,

  2. Comment by tech date 9 July 2016 alle 22:19 (),

    Shaun,
    All of this is in regards to professional things, not what you’d do on your personal time or twitter. The issues here are dealing with things you would be doing for work. While I appreciate your opinion, and its a good one, this particular course gives you the tools you’ll need to get in to the career which includes all of these things. I can see where you’re coming from though. Here is the silabis from the course to give everyone an idea of what we’re getting in to.


    Course Meeting Times:
    Continuous
    Office Hours:
    Continuous
    Course Description

    Instruction ManualTechnical writing is the art and science of translating technical information into readable, accessible writing usable by a wide audience. If you have ever read the user’s manual for a piece of software or equipment you’ve purchased, you’ve seen technical writing in action. Creating manuals, help and technical support systems, online help systems, and instruction manuals are some of the main projects technical writers take on. Since nearly every business in every industry imaginable has at least an occasional need to bring technical information to its users and customers, technical writing is found in nearly every business, governmental, and non-profit arena.

    If you work in a high tech industry, technical writing may be a part of your job description. If you love to write, enjoy learning, and have an interest in technology, technical writing can be an exciting, rewarding career in itself. Job opportunities in the field are expected to grow as technology continues to advance.

    Whether you are called upon to communicate technical information to clients and coworkers, or you are thinking of technical writing as a new and interesting career, this course is designed to help you get started. We’ll talk more about the kinds of products technical writers get involved in, and discuss the kinds of skills that successful technical writing requires. We’ll talk about ways to approach and organize a technical writing project, and look at the kinds of materials technical writers produce, from written manuals to video tutorials. For those looking at technical writing as a new career, we’ll discuss ways of improving your skill set, getting training, making contacts, and breaking into the field.
    Course Materials
    All course material will be provided in the lessons and netlinks. There are no required materials to purchase before taking the class.
    Course Requirements
    This course will not require you to have previous experience in any particular area but you should have a high school reading level. No books will be required.
    Course Topics

    Lesson 1: What is Technical Writing?

    A. Technical writing defined

    B. Who does technical writing?

    a. Engineers, project managers, developers

    b. Technical support staff

    c. Specialists in technical writing

    C. What fields use technical writers?

    a. Software

    b. Consumer and industrial electronics

    c. Medical procedures and equipment

    d. Any field where technical information needs to be made accessible to lay learners

    D. About this course

    a. Introduction to the kinds of projects technical writers work on

    b. Things to consider when approaching a technical writing project

    c. A look at the kinds of materials technical writers produce (and they’re not all written!)

    d. Information on building a career as a technical writer

    Lesson 2: Projects for Technical Writers

    A. software documentation

    a. online help files

    b. user’s manuals

    c. quick start guides

    B. Product and equipment manuals

    a. Hard-copy user’s manuals

    b. Online support

    c. Instructional materials

    C. Other formats for technical communication

    a. Wikis

    b. Audio and video documentation and instruction

    c. Creative formats

    i. Google’s browser manual written as a comic book

    d. webinars

    Lesson 3: The Technical Writing Process

    A. consider the audience

    a. what general level of skill and experience does the end user have?

    b. Which terms can be used freely, which terms need to be define, and which terms should be avoided?

    c. What style of writing will best communicate with the end user

    d. Which information is most critical for the user’s successful use of the product?

    B. Define the deliverables

    a. Choices, choices. The array of formats available for technical writers is growing.

    i. Hard copy manuals

    ii. Electronic documents (pdf)

    iii. Online help platforms

    iv. Multi-media

    v. Wikis

    vi. Blogs

    b. Which deliverable gives the producer maximum benefit for the least cost?

    C. Learn the technology

    a. Consulting S.M.E.’s

    b. Learning from other users

    c. Learning for oneself

    d. “meta-learning:” the successful technical writer doesn’t just learn the application, he or she watches the learning process, noting where it is challenging and what pitfalls tend to slow it down. Meta-learning is invaluable when the time comes to help others learn

    D. Organize the knowledge

    a. Toward a project outline

    b. Multi-sourcing vs. single sourcing

    c. Getting feedback from colleagues, SME’s, and users.

    D. Write and revise the draft. For details on the nitty gritty of good technical writing style, see Lesson 5

    Lesson 4: How to Write effectively: At it’s core, good technical writing is simply good writing about technical subjects. Here are some general guidelines on producing clear, understandable, readable writing that will help your readers gain the information they need.

    A. Clarity and simplicity.

    i. Write like you talk

    ii. Simplify when you can

    iii. Use examples

    B. Correct grammar and punctuation:

    i. Using reference materials

    ii. Using Style manuals

    C. Use visual aids

    i. Graphs

    ii. Photos

    D. Style and the technical writer

    Lesson 5: Teaching an Alien to Drive: If you’ve ever taught a teenager to drive, you know you don’t really have to start from scratch. The average kid will know where to put the key and how to start the engine just from watching his parents do it. But what if an alien landed on earth and asked you to teach it to drive? Successful technical writing is all about giving your audience the information it needs without going too far over or under its head. Let’s watch technical writing in action as we teach an alien to drive.

    A. Breaking down the steps

    B. Defining terms, explaining concepts

    C. Selling the benefits

    D. Creating the deliverable

    Lesson 6: The First End User: You

    A. How to learn new applications quickly

    a. Do you have the love?

    b. Ask dumb questions

    B. Get to know your own learning process

    a. S.M.E.’s

    b. Watch someone else

    c. Relax

    C. Document your progress

    a. What’s hardest about learning this application

    b. What’s easiest

    D. The butterfuly net and the jar: catching bugs and resolving issues

    a. Technical Writers as beta testers.

    b. Don’t be a witch hunter

    E. Zen mind, beginner mind

    a. Keep the beginner in mind, no matter how skilled you get

    b. Be mindful as you learn

    Lesson 7: Getting it Done. Project Management and the Technical Writer

    A. Defining a timetable

    a. When does the product launch?

    b. Is the product finished?

    c. Who makes the decisions?

    B. Assigning Tasks

    a. Do you have a staff, or are you on your own?

    b. Outsourcing and the technical writer

    C. Collaboration

    a. Dealing with SME’s

    b. Keeping everyone on track

    c. Check your ego at the door

    D. Feedback from users

    a. Is the documentation working?

    b. Are you using the best deliverable medium?

    E. Keeping momentum

    a. Keep an eye on the calendar

    b. See how far you’ve come

    F. Staying on top of it.

    a. Dealing with writer’s block

    b. Dealing with slowpokes

    Lesson 8: Words, Pictures, and Links: The Growing Array of Deliverable Formats

    A. Put it in Writing

    a. Hard Copy

    b. PDF

    c. Web pages

    d. Blogs

    e. Wikis

    f. Quick Start Guides

    B. Worth a thousand words: Other Media and the Technical Writer

    a. Video

    b. Screencasting

    c. Podcasts

    d. Novelty

    i. Google’s comic book style user manual

    Lesson 9: Breaking into Technical Writing.

    A. Is technical writing for you?

    a. Are you good at explaining and teaching?

    b. Do you love to learn?

    c. Can you learn quickly?

    d. Can you manage large projects?

    e. Can you write clearly and plainly?

    B. Degree and Certificate Programs

    C. Networking

    a. Join the STC

    b. Put a profile on LinkedIN

    D. Learning the Tools

    a. Who’s using what?

    b. Studying employers’ needs and software requirements

    E. Building a Portfolio

    a. Get your hands dirty

    b. Trial software and help files

    c. Floss Manuals

    F. Types of jobs for technical writers

    a. Full time

    b. Contract

    c. Freelance

    Lesson 11: The Tech Writer’s Toolbox

    A. Software

    a. Robohelp

    b. Doc to Help

    c. DITA

    d. Visio

    e. Blogging platforms

    B. Code

    a. Html and css

    b. Xml

    c. Java

    Lesson 12: Staying in touch with the user

    A. Web 2.0 and the global village

    B. Meet your users

    C. Setting up an maintaining a tech support blog

    a. What to post?

    b. How often?

    c. Dirty laundry – should you publicize your company’s mistakes?

    d. Comments: a gold mine of user experience data

    Lesson 13: Join the Community

    A. The tech writer blogosphere

    B. Writer River

    C. Starting your own Technical Writing blog

    D. Sharing knowledge – everybody wins

    E. Staying on the cutting edge

    Conclusion.

    Technical writing can be a skill you need from time to time in developing a product, or it can be a dynamic, rewarding profession. As technology invades every corner of our daily lives, good technical communicators will be in even greater demand.
    Grading Policy
    Each lesson will include a lesson review quiz along with one or two assignments. Students will successfully complete this course with 70% or better.


    Maybe this will help in your thinking of what I’m writing although you’re not wrong, and technical writing today can mean anything. What are other thoughts?

Sorry, the comment form is closed at this time.

go to sections menu


navigation menu

go to sections menu