User talk:Soniakeys/Go

Book Title
Maybe "Complete Go," especially if I can get a coverage tool working that can validate that 100% of the language reference is covered.

Style
These are guidelines for consistency in the book, both in content and presentation.

Flow
Part 2 of the book is not organized by language structure, like a reference manual, but in fact does ultimately cover everything from the official language reference. Each chapter introduces a set of new elements of the language reference and shows the reader how to do something with them. The example can be completely understood with the new elements plus some minimal set of previously introduced elements. Each chapter builds on elements introduced in previous chapters, although not necessarily on all preceding chapters, or even on the immediately preceding chapter.

In addition to explaining elements of the language reference, each chapter should have a focus on some capability. The chapter should enable some significant step in the programming capability of the reader. This should help a chapter be coherent on it's own if the reader has some preliminary grasp of the language, but otherwise make the book an interesting read from beginning to end.

This focus is documented in a standard way in the talk page for the chapter. Each talk page will have a Focus heading, and under that, a succinct focus statement. The focus statement should identify one single concept, theme, or language capability that is most interesting in the chapter. Never mind that other concepts are covered; the focus statement nominates one as the chapter focus. These statements, compiled into a list, will give a perspective on the flow of the book. The list is manually compiled here for now. A bot would be nice at some point for automatic compilation.

Coverage tool
I want a coverage tool that will cross reference the book with the language reference manual and produce 1) a coverage report, 2) a link box for each chapter, 3) an index page for the book. Maybe pywikibot can do this.  My current thought is to have a Reference section on the discussion page of each example chapter.  Under the heading, one per line, will be snips of text from the reference manual, representing language reference topics covered.  Each snip will be preceded by a character and a space.  The character will be either a number or *.  A number indicates the number of sentences of the language reference that are covered.  * means the entire section of the language reference.  For example,

Reference

* Each source file consists of a package clause

1 A package clause begins each source file

Snips are expected to be found uniquely in the language reference. The coverage tool will report if a snip cannot be found or if it is not unique. The coverage tool will locate the named anchors in the language reference and consider those to be section names.

The coverage report will give percent of language reference covered, a list of section names not covered at all, and for sections partially covered, the text remaining that needs to be covered.

A link box in each chapter will contain links to the sections in the reference manual on the Go website. It can probably go near the top of the page and be labeled "The Go Programming Language Specification has information on these topics." One box for all links will be tidier than separate links scattered through the page.

The index will list sections from the reference manual and list for each the links back into the book. For a printed version these become page numbers.

Three kinds of sidebars
The current template for these is Robox. Really I want them to float right and for text to flow around them, but Robox will do until I figure that out.
 * CompSci 101: basic concepts of programming, not specific to Go. Stuff to help beginning programmers, comments on algorithms and techniques used in the examples.  Robox|theme=2
 * It's different for Go: differences between Go and other programming languges. Specific languages can be mentioned, or whole classes of languages.  Robox|theme=1
 * Concurrency: Not exactly basic concepts of programming, but not exactly elments of the Go language specification. Concurrency techniques used in the examples, how they are enabled in Go, context for them in the general field of concurrency.  Robox|theme=3

Sources of example programs
First choice: try to come up with ideas out of your head. Other ideas though:
 * my blog
 * other Go blogs
 * reference Wikibooks: Algorithms, Data Structures (a la Ada wikibook.)
 * the Go standard library
 * the Go test/bench directory
 * Programming Praxis
 * Rosetta Code
 * sites that Rosetta Code lists as similar (they have a good list)
 * Project Euler
 * programming contest sites
 * programming homework sites. (Aw, for the longest time I held on to a collection of programming problems collected from my homework and contests, all on rumpled paper, all now lost...)