27

I usually read a lot about programming related stuff. When the topic I read is not related to my work directly ,(say reading about some Algorithms which I don't use in everyday work), I forget them.

One way to reinforce what has been learnt is to write blogs. I am a beginner in writing blogs. When I started writing, I figured out that it is very tough. Even simply reproducing the content takes about two hours. Writing a well thought about blog often takes a whole day or sometimes a weekend.

Is this normal? Any tips to write technical tutorials/technical blogs?

Improve this question
3
  • use more examples (that can be copied and work out of the box)
    – Petah
    Jun 3, 2011 at 11:37
  • instead of calling it a fancy blog, just call it Vinoths Notebook.
    – user1249
    Jun 4, 2011 at 11:31
  • I'm with you. I have about 100 drafts on my blog that I've started and never seem to have the time with my work duties to get into publishing form. I don't know how bloggers that post multiple times a week do it without making it a full time job.
    – JohnFx
    Jun 4, 2011 at 16:08

8 Answers 8

Reset to default
24

Writing is hard, good writing is even harder. The thing about trying to explain something is that it requires more knowledge then just "kinda know it". I find that by blogging I 1. find out related topics that I need to understand, 2. identify where my understanding is shallow

Read through these slides http://www.ai.uga.edu/mc/WriteThinkLearn.pdf. They explain a lot about writing (and even compares it to programming)

Improve this answer
3
  • I'll add the same is true of writing a book or generally trying to explain what your brain just 'groks' to a wider audience. Just remember to always try and use a crutch (e.g. Why the reader wants to know this bit of info)
    – Martijn Verburg
    Jun 3, 2011 at 14:04
  • 1
    +1 Mark Twain famously said "I didn't have time to write a short letter, so I wrote a long one instead." His point was that writing short involves writing long and editing down.
    – Ross Patterson
    Jan 25, 2013 at 5:18
  • 1
    @RossPatterson: answers.google.com/answers/threadview?id=177502 Mark Twain was likely not the source of that quote.
    – whatsisname
    Jan 25, 2013 at 6:12
18

Every work of quality requires time and effort. It is to be expected.

Some of my older blog writings took about 3 weeks to complete. You write a draft, reread it, make the necessary corrections, scan it again then proof-read it. It takes time.

One simple idea how to keep yourself motivated. If you're planning on something large, consider if would make sense to split the work in 2-3 parts and publish them separately. The parts need of course be useful to your readers on their own. Then as they take less time you're more likely to make it through and bring the partial work to completion.

Improve this answer
1
  • 6
    +1: The thing about technical blogs is that they aren't really blogs. A technical "blog" is really a collection of essays. Exactly as you've described here.
    – Joel Etherton
    Jun 3, 2011 at 15:31
7

Some tips from this unknown technical blogger:

  • Verify (not just read) code that you've entered by cutting and pasting from the preview to the command line or a text file to run. Several things (like line endings, indentation, and Unicode characters) can get messed up when transferring from an editor (or shell) to a web page and back.
  • Get a human to check spelling, grammar and contents - It shows that some effort went into making the articles correct and easy to read. If nobody is around, make sure to re-read the entire article before publishing.
  • If the blogging platform has syntax highlighting, use it. If not, post the code somewhere that has it and link there.
    • Corollary: Keep huge chunks of code away from the article text. This is a bit vague, but if the text is explaining how some code works it's fine to include a snippet. If it's presenting a piece of software to be downloaded it's better to refer to a VCS web interface.
  • Every article should be readable on its own. Referencing other articles is fine, but don't just assume that the reader has read any other posts before this one.
  • Use other formats than text when they aid comprehension. For some things the code is sufficient, but for some an image or even animation might be much more comprehensible.
Improve this answer
1
  • 1
    Whatever you're using as your blog software, make sure there is a print.css for it. This ensures that only the post's content gets printed. More people are still printing web pages than you'd think.
    – Adrian J. Moreno
    Jun 3, 2011 at 15:40
2

Often I find that a difficult blog post takes so long because it requires research; that research doesn't just help your blog post, but it helps you build up your own personal knowledge in the process. As you said, you're reinforcing knowledge by writing the post; you're also expanding your knowledge. Embrace the time it requires and value it as a learning experience.

Improve this answer
2

Yes, it is normal for technical blog writing to take time. For me, the writing takes the shortest amount of time (as short as an hour, or up to a day, depending on the length). Then the editing and the rewriting typically take longer (up to two or even three days). Another aspect that's been mentioned that takes time is clarifying any sample code. Also, I like to spend time finding supporting links for my topics. It all takes time!

Improve this answer
0

I guess you could write technical blogs now But I would suggest you to do so when you become expert in some particular domain. Spending a weekend does not seem too much time. it all depends on the complexity of the topic. I guess what i am saying is that the core of your idea shud come to you naturally Execution might(and will) take longer.

People are looking for some experts advice in a blog .. not a noobs experiments. but i am talking in a general sense .. I do not want to discourage to you write blogs. But keep the following things in mind.

1. Your blog should say something new. Do not just gather data and put it up on your own blog

2. Be absolutely sure of what you are saying i.e. stick to strong empirical results or highly tested concepts or stuff you have experienced first hand .

3. Be ready for criticism.

4. Learn the techniques of writing blogs (preciseness, conciseness, etc)

5. Write something because you think it shud be written; not because you think it will be read .

Improve this answer
4
  • 4
    "I would suggest you to do so when you become expert in some particular domain". I disagree with this statement. He can have a technical blog where he has posts of stuff that he has learned and wanted to share with everyone else. In fact, I was thinking of doing the same type of thing myself.
    – Jon
    Jun 3, 2011 at 13:05
  • Yeah, I know someone that posts an incredible amount of stuff they haven't the faintest idea about. However, those posts are about how they worked through learning those things or how they went about figuring out something new about some thing.
    – Adrian J. Moreno
    Jun 3, 2011 at 15:42
  • @jon @kungfu you two shud write diaries then ! why put others at risk from your ill-concieved, non-expert advice? and who do you think would read such stuff anyways ? (except for you maybe)
    – Chani
    Jun 6, 2011 at 12:31
  • If everyone thought that, there would hardly be any blogs at all. Even MSDN blogs have posts based on their experiences and how they solved them.
    – Jon
    Jun 6, 2011 at 13:27
0

The Elements of Style

I think technical writing follows much of the same rules as any writing. If you only read one book about writing it should be the classic Strunks "The Elements of Style". It goes through a list of things that will improve your composition, the foremost being (IMO), "Omit needless words".

I'd also recommend Stephen King's "On Writing". While being more about fictional writing it still contains plenty of gems for any aspiring writer, especially in areas such as editing and the process of writing.

That being said the hard thing about technical writing is not the actual writing but clarifying your thoughts about the thing you're writing about. Muddled thinking leads to bad writing. Good writing require you to have a clear grasp about your topic, which is why teaching and writing is such an excellent way to master a subject.

Improve this answer
0

Well, it takes me an awful lot of time to write blog posts, yeah. I frequently write them over several days, or even leave them around in draft form for a couple of weeks, occasionally reading over them again and correcting and tweaking a bit here and there.

It takes time, but if that's the price for writing something I'm not ashamed of afterwards, I thnik it's worth it.

Improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.