SitePoint Sponsor

User Tag List

Results 1 to 6 of 6
  1. #1
    phpLD Fanatic bronze trophy dvduval's Avatar
    Join Date
    Mar 2002
    Location
    Silicon Valley
    Posts
    3,626
    Mentioned
    3 Post(s)
    Tagged
    0 Thread(s)

    Keys to Writing Technical Articles

    If you are like me, if you see too much code, and things aren't explained where it makes total sense, you stop reading. For me the article needs to:
    1. Be easy to follow
    2. Convince me that I should spend more time on this technical idea

    Any tips to drawing people into reading technical articles?

  2. #2
    SitePoint Addict wardcosbyson's Avatar
    Join Date
    Nov 2010
    Posts
    253
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Since your readers will come from various countries with different levels of understanding, then you need to write your articles in the most simple manner you can.

  3. #3
    SQL Consultant gold trophysilver trophybronze trophy
    r937's Avatar
    Join Date
    Jul 2002
    Location
    Toronto, Canada
    Posts
    39,260
    Mentioned
    60 Post(s)
    Tagged
    3 Thread(s)
    there is no technical data that cannot be more beautifully communicated than with well chosen charts, graphs, illustrations, and drawings -- just ask tufte

    rudy.ca | @rudydotca
    Buy my SitePoint book: Simply SQL
    "giving out my real stuffs"

  4. #4
    SitePoint Member
    Join Date
    Dec 2010
    Posts
    19
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Well, if we specifically talk about technical 'writing' only, we must give pointers and make them as manual guides or 'How to' articles.

  5. #5
    SitePoint Guru bronze trophy
    Join Date
    Sep 2006
    Posts
    949
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    only, we must give pointers and make them as manual guides or 'How to' articles.
    We must, must we. What if how to fails to serve the reader's interest?

    One of the big problems people have when writing for the web, is failure to communicate the why to. This speaks to point two, in the OP, as being easier said than done.

    Many sites submitted had no concern for the user on the most basic levels. Rarely could you identify an idea or purpose behind the site, or name a possible user goal the site was intended to facilitate. There was no flow, no legibility, no usability. It wasn’t so much that the designers had contempt for their users as that they seemed never to have been taught to think about users at all. One gets the feeling that the web design curriculum at too many colleges and universities consists of little more than tips on how to use Flash to imitate sites that won awards five years ago.

    -- The Rebooter's Children Go Rebootless, Jeffrey Zeldman
    Let's say you're a web dev, and you want to attract clients. What many do, is publish an article about how to develop a site using the flavor of the week (CSS 3, HTML 5, Postgre, Jquery ...whatever).

    What does a client, in general, desire? Well the bare minimum competence of how to get things done, while important, doesn't serve all the client's needs.

    Glacially slow on the uptake, web devs are getting the point if a client wants to know how to build a site without you ....they are less than enthusiastic about hiring you. I call these "How Not To Hire Me" articles.

    At best, you're talking to prospects unwilling to be clients. At its more common worst, you're getting traffic from other devs and designers, who will never hire you. Ever.

    Who is going to pay rock bottom for a service? Someone who thinks they could just as well do it themseves. Yet that's who most how to articles target.

    Zeldman is a web dev guru, of sorts. His criticism carries the weight of someone who understands there's a why to deficit.

    The high-fives stopped. People adjusted themselves in their high-back leather chairs and the bank president stopped pacing and sat down. After a few minutes of discussion it became apparent that there was no objective or strategy in place. The project had no reason to exist except that the client wanted a website and the web designers sitting across from me liked money, so it seemed like a natural fit. Oops.


    -- Never Get Involved in a Land War in Asia (or Build a Website for No Reason)
    My suggestion is to never write plain, simple technical articles explaining how to do it yourself and never hire you. ...Ever.

    Stop writing plain clear how to articles about Zen Cart. Start writing articles about ecommerce that show clients how to double sales with three quick changes to any shopping cart. And why shopping cart developers could care less about sales, because all they support is the transaction at the end.

    Stop writing articles about how to post an article in Wordpress. Start writing about how to use Worpress to accomplish actionable business goals. If the company needs education on the operation of a ten button text editor window UI, with tooltips, they've got much bigger problems.

    Stop writing articles about how to install the latest technology. Start communicating your understanding about the reason why your clients should care.

  6. #6
    SitePoint Member
    Join Date
    Dec 2010
    Posts
    19
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by DCrux View Post
    We must, must we. What if how to fails to serve the reader's interest?

    One of the big problems people have when writing for the web, is failure to communicate the why to. This speaks to point two, in the OP, as being easier said than done.



    Let's say you're a web dev, and you want to attract clients. What many do, is publish an article about how to develop a site using the flavor of the week (CSS 3, HTML 5, Postgre, Jquery ...whatever).

    What does a client, in general, desire? Well the bare minimum competence of how to get things done, while important, doesn't serve all the client's needs.

    Glacially slow on the uptake, web devs are getting the point if a client wants to know how to build a site without you ....they are less than enthusiastic about hiring you. I call these "How Not To Hire Me" articles.

    At best, you're talking to prospects unwilling to be clients. At its more common worst, you're getting traffic from other devs and designers, who will never hire you. Ever.

    Who is going to pay rock bottom for a service? Someone who thinks they could just as well do it themseves. Yet that's who most how to articles target.

    Zeldman is a web dev guru, of sorts. His criticism carries the weight of someone who understands there's a why to deficit.



    My suggestion is to never write plain, simple technical articles explaining how to do it yourself and never hire you. ...Ever.

    Stop writing plain clear how to articles about Zen Cart. Start writing articles about ecommerce that show clients how to double sales with three quick changes to any shopping cart. And why shopping cart developers could care less about sales, because all they support is the transaction at the end.

    Stop writing articles about how to post an article in Wordpress. Start writing about how to use Worpress to accomplish actionable business goals. If the company needs education on the operation of a ten button text editor window UI, with tooltips, they've got much bigger problems.

    Stop writing articles about how to install the latest technology. Start communicating your understanding about the reason why your clients should care.
    Thanks for this much descriptive explanation and unveiling the secrets of real content writing.


Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •