[Swift-devel] user guide work

[Mihael Hategan]

On Mon, 2015-05-18 at 13:27 -0500, Ketan Maheshwari wrote:
> I think Swift is a special purpose language where ~20% of features are
> used for ~80% of cases. Consequently, providing a K&R style language
> manual might not be the most valuable thing for a user to read. It
> also runs a risk of coming across as a general purpose language which
> may mislead readers.
> 
> I think, a document structure where the important features (app and
> builtin functions, variables and mappers (with examples)) are
> highlighted in the early parts and details such as variable scope,
> expressions, operators etc. are described in the middle and concluded
> with sites specific details might serve well.

You mean like a brief overview of important things / tutorial in the
beginning?

Or do you mean that the language reference should not have a bottom-up
structure, starting with the simple/primary concepts and building up
from that?

Mihael

> 
> --
> Ketan
> 
> On Sat, May 16, 2015 at 4:04 PM, Mihael Hategan <hategan at mcs.anl.gov> wrote:
> > Hi,
> >
> > Mike pointed out that I should probably post a link to what I'm trying
> > to do with the user guide just in case things are going awfully wrong.
> > So here it is:
> >
> > http://www.mcs.anl.gov/~hategan/ug/ug/ug.html
> >
> > Mike mention K&R a number of times and I think I like that general idea.
> > The above, so far, is a mix between K&R Chapter 2 and Appendix A.
> >
> > The main idea is to keep things concise by separating parallelism
> > behaviour from what a program actually does. In that sense, one would
> > first describe the language, and then go into the details of how a
> > particular implementation goes about running programs.
> >
> > I'm not particularly opposed to starting with a brief tutorial in the
> > spirit of K&R Chapter 1.
> >
> > Mihael
> >
> >
> > _______________________________________________
> > Swift-devel mailing list
> > Swift-devel at ci.uchicago.edu
> > https://lists.ci.uchicago.edu/cgi-bin/mailman/listinfo/swift-devel