Programmer's Diary: Writing a Series for @NetTuts

If you are following me on twitter you probably know I am a regular technical writer for +Nettuts+ . I write various tutorials and articles on programming topics. However I never wrote a series with tutorials that are connected in one way or another.

That changed with the series on the SOLID principles. I had to write four articles covering five principles and I found out there are quite a few challenges when writing a series of articles.

Challenge #1 - The first article must be good. Much better than any of my stand-alone articles, because it must convince any reader, new or regular, that the upcoming articles in the series deserve their attention. The first article has the stake of the whole series. If it fails, there is a chance the rest will never be read, doesn't matter how well written it may be.

Challenge #2 - Each article must find a way to refer to, to connect with the previous articles or at least with some of them so that the readers have a feeling of continuity. In each of my SOLID articles I referred to at least one, but preferably two other SOLID principles. Now, this is again tricky. Because the articles are published and read in sequence, from S to D, even though O may relate to I or D, in the article itself I can only refer to S because the reader may not know about the LID principles. If I refer to any of LID I risk one of two things: confusing the reader and loosing him/her, making the reader curious and making him/her read the three LID principles from other sources and not read my upcoming three articles.

Challenge #3 - Each article must be self contained, in a sense that a new reader must be able to comprehend it without reading any of the preceding or upcoming articles in the series.

Challenge #4 - Each article must provide something different so that the readers don't get bored. If one article explained the concepts with mostly text in anecdotal manner, the next one must use a different approach, maybe more schemas or more source code or more quotes of rules and definitions or more funny statements. It doesn't really matter what, but it must be different, it must be unique in a way to disrupt the monotony of the series and still provide the valuable information it proposed as its topic.

Challenge #5 - The last article must contain a conclusion to the whole series. It must be written in a way that not only transfers the last topic in the series, but also connects all the dots and provides a high level view over all the topics presented throughout each tutorial. It also has to put everything in perspective, under a different light, in a different - bigger - universe, where the whole series is just a small piece of the puzzle.


That's why I concluded my series about the SOLID principles with a reference to The Magical Number Seven, Plus or Minus Two and that is why there are 5 challenges in this blog post.