[Swift-devel] user guide work

Mon May 18 17:04:32 CDT 2015

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 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.

--
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