[Swift-devel] user guide work

[Mihael Hategan]

Right. This is pretty close to what K&R does.

I was personally thinking the following: intro, language reference,
runtime reference, tools reference. It's not trying to sell anything or
emphasize anything. You use it when you need answers. You don't really
read it. You scan it for what you need, and then read the parts that are
relevant to what you are trying to do. The order is from basic concepts
to more complex ones. It's an order that most people would expect,
especially people that have little experience with swift. It is like
that because the purpose is for a user to quickly find the information
they need, not for us to point out to users what we think is cool about
our stuff.

What you describe is fine. And there is no reason why the two things
cannot coexist. Which is the general idea that I think we discussed
during the last meeting. There's formal documentation and there's
informal introductions / tutorials. The latter are different. You read
them sequentially, like a book. The order is the order in which things
are important in swift. You wouldn't start with types and variables.

Mihael

On Mon, 2015-05-18 at 15:27 -0500, Ketan Maheshwari wrote:
> I think a little bit of both.  A brief overview of important things
> with examples in chapter 1. Then, topics like "Task Parallel
> Computing" or "Many Task Computing" may cover foreach, futures and
> task parallelism as implemented in Swift. Then, a chapter like "File
> I/O" may cover the mappers, etc. Then a topic like operators and
> variables may bring in more of the language reference in that
> describing types, structs, etc. Next may be builtin functions.
> Followed by a chapter on Compute sites which covers Resource and data
> managers, remote access and providers and such.
> 
> So, to elaborate here is a rough outline I have in mind:
> 
> Chap 1. Swift Overview
> -- Importance of Swift
> -- Swift example 1
>    -- hello world, description, concept show in this example
> -- Swift example 2
>    -- Run an app functions, describe importance of app functions
> -- Swift example 3
>    -- Do file mappings, describe mappers
> -- Swift example 4
>   -- Do foreach loop, describe foreach
> -- Swift example 5 (if needed)
> 
> Chap 2. Many Task Computing in Swift
> -- Parallelism in DAGs
> -- Futures
> -- foreach loop and variants
> -- iterate
> 
> Chap 3. File I/O
> -- File types
> -- Simple file def
> -- Complex Mappers
> -- Read and Write to Files
> 
> Chap 4. Variables and Operators
> -- types
> -- structs
> -- import
> 
> Chap 5. User defined and Builtin functions
> -- string
> -- numerical
> -- stat
> -- math
> 
> Chap 6. Swift providers
> -- Coasters
> -- Data providers
> -- Compute Providers
> 
> Chap 6. Remote compute sites
> -- Modes of running
> 
> Appendix A. Swift Grammar in BNF
> Appendix B. A table of Swift conf options
> Appendix C. Swift cheatsheet
> 
> 
> On Mon, May 18, 2015 at 2:20 PM, Mihael Hategan <hategan at mcs.anl.gov> wrote:
> > 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
> >
> >
> > _______________________________________________
> > Swift-devel mailing list
> > Swift-devel at ci.uchicago.edu
> > https://lists.ci.uchicago.edu/cgi-bin/mailman/listinfo/swift-devel