[Swift-devel] user guide work

Mon May 18 16:52:19 CDT 2015

On Mon, 2015-05-18 at 16:48 -0500, Yadu Nand Babuji wrote:
> The overview sounds a lot like the tutorial. I think it's better to have 
> tutorial-like material just go into the tutorial rather than just get 
> duplicated in the userguide.
> If the tutorial does not give the user an adequate picture of items in 
> Ketan's overview, the tutorial needs fixing.

The tutorial can link to the more formal documentation. It's a form of
"hey, if you really want to know...". 

Mihael

> 
> The webpage points users to the tutorial, and if the tutorial isn't 
> adequately covering the useful 20% of the language, I suspect that they 
> wouldn't bother to get to the userguide.
> 
> Thanks,
> Yadu
> 
> On 05/18/2015 04:34 PM, 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
> > _______________________________________________
> > 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