[Swift-devel] user guide work

[Mihael Hategan]

The link I posted is not the first chapter. It is one piece of the
documentation.

Mihael

On Mon, 2015-05-18 at 16:34 -0500, Ketan Maheshwari wrote:
> This is true except for the first chapter. First chapter is going to
> be read by a significantly larger number of people and the rest of it
> would be ctrl-f'd. I think we may want to push some stuff further down
> in the user guide than what is in the link you originally posted.
> 
> --
> Ketan
> 
> On Mon, May 18, 2015 at 4:18 PM, Mihael Hategan <hategan at mcs.anl.gov> wrote:
> > 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
> >
> >
> > _______________________________________________
> > Swift-devel mailing list
> > Swift-devel at ci.uchicago.edu
> > https://lists.ci.uchicago.edu/cgi-bin/mailman/listinfo/swift-devel