The following discussion is relocated from Category_Talk:C tutorial. --Netocrat 04:40, 27 June 2006 (BST)
I am thinking of maintaining a clean structure with chapters - just like chapters in Category:KR2_Solutions. I think the having names like "C_tutorial_Chapter_1" although a bit big, is nice. Any other suggestions?
- I've seen an extension that allows for chapter-structuring that looked reasonable; there may be others. Something like that would be useful for our wiki for the FAQ and tutorial. --Netocrat 18:33, 20 February 2006 (GMT)
Also, a feature that would create a box that pin-points specific features or deters programmers from common mistakes would be nice - for example "Hint: Do not ever declare main() to return void because blah blah blah. For more see FAQ Question xx.xx and ....". Is there something like that?--dop 09:27, 20 February 2006 (GMT)
- Not out-of-the-box afaik. The way to go about that would be through a template. Check them out in the wiki user guide on meta. There are probably plenty that you could copy across from Wikipedia. HTML rendering is enabled on clc-wiki too.--Netocrat 18:33, 20 February 2006 (GMT)
Since there were some cooperation problems, we must specify - at least partially - what will the tutorial contain and in what order. Also, we must propose a style "guideline" - that is, we do not think that "technical writing needs to be totally bland though, even when brevity is required" (Netocrat). --dop 10:45, 15 March 2006 (GMT)
Style
- Small paragraphs to keep it visually appealing and easy to read. The optimal should be between 2-5 lines.
- Clear language, so even non-native English speakers can understand it.
- The target group is novice programmers or more experienced ones. Should we create a big part of this tutorial, we may even target also to people that use this to start with a computer language. However the latter ar better off to get K&R.
- Small examples - that can be read without going up and down the page if possible - with proper identation according to clc-wiki style guidelines. Some kind of a script or a template that adds line numbers to code would be nice - however, the code should also be easy to be directly copied to an editor and be compiled without having to remove the line numbers. Is this possible in wiki or needs another script (having a table with 2 columns and 1 row, with the first column having the line numbers and the second the code would be enough).
- Several information boxes should be defined and create templates for them: we need a box for "DID YOU KNOW THAT" that has some trivial information that readers might not be familiar with, "WARNING" to make sure that a reader might not make a common error (for example declaring main()) and "HINT" for making suggestions on another approach on the code and maybe style.
Proposed tutorial structure
The structure was created having in mind what I've read in 2-3 books and without having any of these in front of me. If I forgot something, please add it, but do not recreate the structure of any book --dop 10:45, 15 March 2006 (GMT)
- Chapter 0: Introduction to the tutorial and "Hello World" program. Testing chapter for the whole tutorial.
- Chapter 1: Variables, variable initialization, arithmetic operators.
- Chapter 2: if, for, while, do while, switch, goto (a simple reference for completeness), break, continue
- Chapter 3: struct, union, enum, typedef
- Chapter 4: Functions
- Chapter 5: Arrays (should we move this up?)
- Chapter 6: Pointers
- Chapter 7: stdio
- Chapter 8: Advanced Pointers, Function pointers
