Tutorial Code vs Real Code: A decision

by percent20 2. December 2007 08:58
The goal I have set out is to provide easy to understand content for beginner developers.  As such I want to follow specific guidelines:

1) Real-world code (if possible) or Real-world Context
2) All code being shown in an application
3) Explain all code no matter how mundane or repetitive of previous posts

These are very noble goals some people have pointed out to me, but not necessarily possible.  From what I can tell beginners like well thought out explanations and easily understandable tutorials with little to no problems understanding, this is one reason video tutorials are popular.  However, this presents a problem in the world of text as it will lead to REALLY long tutorials that can be overwhelming at times for the writer and beginner. Therefore, a lot of people compromise with code snippets explaining only a piece and leaving some people going "huh".

As I have been working through an example application for my TDD series I am running into a design problem.  Do I show bad practices, because I hate the "don't use this code but here you go" statements that some tutorials have, or do I show workable code that "could" be used.  The benefit of quick and dirty code is I get the point across quickly with little space taken up, but I alienate those that want to understand but there isn't enough information in the tutorial.  The benefit of long detailed tutorials is just that they are long and detailed explain many parts of code to help a maximum amount of people, but they can tend to be to long and drawn out and lead to reading fatigue.

Solution
Go for broke.  From personal experience I prefer long drawn-out well rounded tutorials that explain things well beyond code snippets that barely explain it.  So I'd rather have fewer readers and thorough posts with quality code over shoddy code and quick posts. So basically when I do a series expect there to be a lot of parts because I want to explain ever bit of code, and all the code will need to be usable in any place. Now it doesn't mean that the code can't be better, but it will work.  Also for those that may not want to read through everything I will post up the completed project so they can download and have a look.

These are my views on the subject please post comments with your opinions.  I would love to hear them as I could be completely wrong in my thought process's and decisions.

Be the first to rate this post

  • Currently 0/5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

Tags:

Comments

Add comment


(Will show your Gravatar icon)  

  Country flag

biuquote
  • Comment
  • Preview
Loading



Powered by BlogEngine.NET 1.4.5.0
Theme by Mads Kristensen

RecentComments

Comment RSS