[Swift-devel] Swift reference manual and syntax specification

[Mihael Hategan]

On Sun, 2013-03-10 at 18:07 -0500, Tim Armstrong wrote:
> Aside from formal specifications, I think one major gap is concrete
> examples that illuminate the trickier points of semantics.  I personally
> find well-constructed examples more helpful for most purposes than formal
> specifications, 

I completely agree. I often found our manual to be lacking. When having
forgotten how to do something, I would go to it, but see no examples of,
for example, how to do a tc.data line.

So I think there are some principles that we should observe when writing
docs, like use only one term for a given concept, don't use stuff before
defining it, and always have examples for everything.

Mihael