How to write good articles about programming in ASP.net and C#?

Question

Over the last 1 1/2 years I've been working as a junior software-developer at a small company with focus on ASP.net / C#. During that time I've read in some great programming books, c# forums, stackoverflow, blogs et cetera and was able to learn much in a short time.

But there was always something I missed: Most of the ~1500 page books cover great areas of programming, but often most of the topics are only truncated. (Of course, because otherwise the books would cover a couple of thousand pages long)

Usually I'm in this kind of situation after reading a new chapter in one of these books:I have basic understanding of what a control/method/whatever does, but I do miss on-project-experience like hints and tweaks that can come very handy. (E.g. If you use control XXX with YYY, you should consider using ZZZZ and not AAA because DDD)

I've stumbled across some of these tweaks and was able to write them down (in a small wiki). Now I feel like I want to share these hints in some kind of tutorial about various different topics. For instance I've never seen a tutorial about ASP.net Theming and Skinning that explains, what Theming and Skinning is, shows basic usage and more advanced usage with code coverage.

Then I thought, hey, why to wait for somebody to write such a tutorial if you can write it yourself? Though this idea sounds simple, I'm having trouble getting started. Questions that pop into my mind are:

• In what levels of technical comprehension level should I write my tutorials (How can I find the balance between beginner and pro)
• How can I write the tutorials that they ain't gonna get boring but still not too short?
• How much code coverage / picture coverage should I use
• What must I keep in mind while writing not the make the same mistakes other authors did?
• How should I structure the tutorials?

Of course the definition of good is very subjective. I do consider this article http://weblogs.asp.net/scottgu/archive/2010/08/18/debugging-tips-with-visual-studio-2010.aspx a nice example, although I can't it compare to my tutorials because I think of them as longer, so the balance between text, code and images should probably be different, but where exactly?

Answer 1

Same way you get good at everything else... practice!

Answer 2

Maybe you can consider writing an article series and not just one article. The series starts with the basics and ends with the advanced technology. So the audience can start reading at the required level of knowledge. Personally I like the series from Sacha Barber at Codeproject.

Answer 3

The first step is to learn from some of the best out there.

1. Scott Hanselman
2. Joel On Software
3. Scott Guthrie's Blog

As for some of your various bullets.

• You need to show enough code blurbs and screen shots to get an understanding, but leave the details/boring parts in source code attached.
• When it comes to details its a balance between what is needed, how complicated the subject, and your target audiences.
• Tutorials can take various approaches, some people like to give "check points" and you have users build upon whatevever you give them stopping at various points and "refreshing" what they did, which gaurentees they have a working POC. Others prefer the "File new" approach and you hold their hand from start to finish.

Everyone has their own style when it comes to both writing and reading. When you find yours writing will be the easy part, and the hard parts will be finding the subject and an audience.

Practice makes perfect.

Answer 4

The best way, I find, to get this sort of knowledge is to read a lot of blogs. Find someone in the community (your local community, or the nation/global community) and follow their blog. Then start following people on their blog roll. Do the same with Twitter (these guys retweet a lot of other excellent bloggers).

To seed that search, I'd start with Scott Hanselman (google him for his blog and twitter). You've already started to follow The Gu, which is another excellent blogger.

From them, you can start to see how people who do it very often write their articles.

Depending on your audience, consider your writing style. Some, like Hanselman, write in a very terse and informal manner. Some like, Scott Bellware, tend to write novels with more complex sentence structure.

You'll also notice the utilization on screenshots and occasional video makes a world of difference. Find a clear, readable way to display code samples or nobody will stick around to read your articles.

If you are really wanting to do step-by-step style tutorials, consider doing screencasts, like you would find at http://dimecasts.net/

Answer 5

With any technical writing I like to follow the "three C's"

• Clear - If your writing is unclear, it can be easily misunderstood or written off altogether.
• Concise - If your writing is longer than needed then it makes it hard to fully understand your message
• Complete - You mentioned a gripe about books not being in-depth enough, if they at least gave you an understanding of their subject at a consistent level of abstraction (ie: you leared enough about WCF from a WCF book to use them, but you don't understand them down to the bare-metal) then you've done well. However, if you leave a gap in the necessary subject matter then it can be extremely aggravating.

If you need to include code-samples, they need to follow this as well. They should contain just enough code to clearly exemplify the subject. The reader shouldn't have to hunt for small nuances which are critical (ie: in Javascript, having () after a function can make a world of difference--so point it out if it's critical).