[Swift-devel] user guide work

[Yadu Nand Babuji]

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