[Swift-devel] user guide work

Ketan Maheshwari ketan at mcs.anl.gov
Mon May 18 18:18:31 CDT 2015 

On Mon, May 18, 2015 at 5:50 PM, Hategan-Marandiuc, Philip M.
<hategan at mcs.anl.gov> wrote:
> On Mon, 2015-05-18 at 17:04 -0500, Ketan Maheshwari wrote:
>> I would argue in favor of some redundancy between user-guide and
>> tutorial. Assuming that most users are busy (and impatient), they will
>> randomly click one link and we will have a better chance to get the
>> point across.
>
> I'm not sure what you are saying. Can you be more specific? With
> examples perhaps?

I mean the tutorial and user-guide need not be strictly mutually
exclusive. At least, the initial sections in both could have some
overlapping, eg. example scripts. Later sections may gradually branch
out into "what+why" for the user-guide and  "how to" for the tutorial.

>
>>
>> I think we should collaboratively develop a ToC for user-guide and
>> tutorial before filling in the details. I think most details exist
>> already, it is a matter of figuring the placements.
>
> As long as we are on the same page about what we want to achieve, then I
> think that's a good idea.
>
> But I disagree that the details are there and that this is a matter of
> shuffling paragraphs around. The details we have are lousy, the grammar
> is lousy, and many things are incorrect. I can give many examples, but
> let's just pick one:
>
> -------------
> Sequential iteration can be expressed using the iterate construct:
>
> step[0] = initialCondition();
> iterate ix {
>   step[ix] = simulate(step[ix-1]);
> }
> This fragment will initialise the 0-th element of the step array to some
> initial condition, and then repeatedly run the simulate procedure, using
> each execution’s outputs as input to the next step.
> -----------
>
> The code doesn't work (it's missing the "until"), the step array is not
> a condition array (it can be anything). The code also doesn't work
> because it will deadlock on step[-1], because the initial ix is 0.
>
> This snippet is in "Arrays and parallel execution", except iterate does
> not do parallel execution. The first paragraph of that section reads:
>
> -------------
> Arrays of values can be declared using the [] suffix. Following is an
> example of an array of strings:
>
> string pets[] = ["shane", "noddy", "leo"];
> An array may be mapped to a collection of files, one element per file,
> by using a different form of mapping expression. For example, the
> filesys_mapper maps all files matching a particular unix glob pattern
> into an array:
> -------------
>
> What's a "different form of mapping expression"? (the context for that
> is many paragraphs earlier). There is absolutely no mention of parallel
> execution or parallelism in the section titled "Arrays and Parallel
> Execution".
>
> Furthermore, Swift has evolved a lot since that documentation was
> written, and very little of that is documented. So no, the details are
> not there.

Ok, agree.

>
> Mihael
>
>>
>> --
>> Ketan
>>
>> On Mon, May 18, 2015 at 4:48 PM, Yadu Nand Babuji <yadunand at uchicago.edu> 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 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
>> _______________________________________________
>> Swift-devel mailing list
>> Swift-devel at ci.uchicago.edu
>> https://lists.ci.uchicago.edu/cgi-bin/mailman/listinfo/swift-devel
>
>

More information about the Swift-devel mailing list