[Swift-devel] user guide work

[Ketan Maheshwari]

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