Talk:A Beginner's Guide to D/Style Guide

Organization
Why are chapters and sections numbered? Doing so will make reorganizing things more diffcult. Is there are benefit for having numbered sections in an Hypertext book? Derek Parnell 07:31, 7 September 2006 (UTC)
 * I agree. I will probably drop the numbering convention soon (though I may still use # in the TOC for clarity) --GregorR 15:13, 7 September 2006 (UTC)

Naming
What is the difference between 'concept' and 'construct' in the names? Can you give examples of what is a 'concept' name as opposed to anything else? Derek Parnell 07:31, 7 September 2006 (UTC)
 * Conditionals are a concept, 'if' is a construct. I will add examples to this page. --GregorR 15:13, 7 September 2006 (UTC)

Dependancies
Remembering that this is a hypertext book and that the audience can come from any background, we should not assume that the book will be always read from start to finish in order. We should be free to insert links to 'future' concepts so that readers can learn at their own pace and style. Derek Parnell 07:31, 7 September 2006 (UTC)
 * I agree, but fundamentally it should still be readable in order, even if it has references to later sections. --GregorR 15:13, 7 September 2006 (UTC)

Attribution
You do realize that the Wiki keeps all revisions along with who wrote what? How does one determine to what level of contribution should the attribution be? Personally, I'm not fussed whether my name is up in lights or not. It a community effort with hopefully many contributors. Derek Parnell 07:31, 7 September 2006 (UTC)
 * The wiki history list is hardly attribution, in my opinion. It's not that I'm obsessed with my own name, I just have a credit-where-credit-is-due attitude.  I'm under the impression that many people will disagree, but it'll take a sizeable amount of convincing to get me to change my mind :) --GregorR 15:13, 7 September 2006 (UTC)
 * If a page has a really significant number of primary authors (a situation which I pessimistically find highly unlikely), it may become necessary to trim down the list to only the biggest contributors. --GregorR 15:16, 7 September 2006 (UTC)

Complexity
The phrase "Users of  will find this section trivial, and can skim it." seems to be talking down to the potential readers, and I think it will be counterproductive. I suspect that if people already know  then they can decided for themselves whether or not a section is trival or relevant. Derek Parnell 07:31, 7 September 2006 (UTC)
 * I didn't intend to imply that that would be the literal phrasing. In many cases they probably can, but I would hate for a C++ programmer to go "classes?  I know classes!" and miss that objects are byref in D, or see "operator overloading?  I know operator overloading!" and miss all the keywords, reversability, et cetera.  A carefully phrased template along the lines of "Programmers familiar with C, C++ or Java are likely to find this section familiar, and are obliged to skim or skip it at their discretion" would allow such readers to quickly discern not only whether they know the concept, but the constructs (hey, I'm making that ambiguous distinction again :) ) --GregorR 15:13, 7 September 2006 (UTC)
 * This is an example of the template as I intended it:

I propose that the Skim templates should be extended by having them link to a summary/notes sub-page that contains information about the differences between the way D handles a concept and the language that the box is for. An example of why this is useful is /The Basics/Introduction to Modules module which currently (as of this comment) has an "Info for Java Programmers" section at the bottom of the module. This sort of information should not belong in the main module text; the main module text should ideally be reserved for text intended for the main target audience of the book-- beginning programmers. The information is useful enough, though, that is should not be deleted outright. A sub-page would be, in my opinion, would be the ideal place for this sort of information. Having summary/notes sub-pages for programmers in other languages would also increase this books appeal to them as they wouldn't have to worry about missing important details if they decide skim a section. Tknott 20:34, 3 December 2006 (UTC)

Console output
I propose that the console output of programs should be in bold monospace font in &lt;pre&gt; tags. This makes it distinct from both book text and code. If nobody objects I will update the style guide and /The Basics/Basic Output/ to use this convention.
 * Updated /The Basics/Basic Output and the Style Guide to include this convention. Tknott 19:36, 3 December 2006 (UTC)