proj-oot-old-150618-ootDocumentation

the official Python tutorial is wonderful

here's a pretty haskell tutorial: http://yannesposito.com/Scratch/en/blog/Haskell-the-Hard-Way/

incidentally, the asm.js spec formatting is pretty.

---

things i learned from the Hoon tutorial (which i didn't like) and the Python tutorial (which i loved) and some of the Haskell tutorials, and On Lisp, and the Scala tutorial, and the Clojure tutorial (which i didn't like):

• there should be a 'features of Oot' showcase document for programming language geeks, like the Scala tutorial. It should have one short example for each feature, with terse explanation.
• there should also be a 'how to write small programs' and 'how to read Oot' tutorial, like my Haskell tutorial plus the Python tutorial
  • this tutorial needs to have a mini-reference "cheat sheet", like i made for Hoon
  • this tutorial needs to be linear, never using constructs in examples that haven't been introduced yet, unlike the Hoon tutorial
  • this tutorial needs to be organized around starting with simple programs and then getting more complicated, NOT around theoretical aspects/pillars of the language, unlike the Hoon tutorial
  • examples should be toy programs, not parts of the compiler
• there should also be a 'for programming language geeks' tutorial like A Gentle Introduction To Haskell.
• there needs to be a language reference
• the language geek tutorial should motivate the features/language/design choices a bit, but the beginner 'how to write small programs' tutorial should not, at least not very much, except insofar as showing how easy it is to write things is motivation itself.
• none of the tutorials should be very witty/funny
• keep in mind that those reading the tutorial have not yet decided if they want to invest the time to 'really' learn the language
• never tell the reader to go read the compiler source to understand something, even if the relevant part of the compiler source is very short and readable
• keep in mind that some readers will want to understand exactly what everything you say means, and will not appreciate 'we'll explain this later, but just pretend ...'. Otoh, you don't have to explain the reduction of syntactic sugar used in the beginner tutorial, the target audience wants to learn the language, not marvel at its design (mb save this for the programming geek tutorial).
• an example of a text that gives good examples (beyond the above ones) is On Lisp
• you may choose to sometimes assume that the reader is an accomplished programmer in other languages and will recognize borrowed syntax, but if so, state each time you do so, and state which other language the syntax element is from/like.

--- small programs tutorial

hello world / intro, print hello world with variable / variable ask name, hello world / variable usage, input arithmetic string manipulation count to ten / for hello world in a while loop? / while guess my number even or odd accept, then print a list / list find highest number in a list / list usage (for hoon) faces, cells? see python tutorial, find basic book i read when younger

---

io's web page style looks nice:

http://iolanguage.org/scm/io/docs/IoTutorial.html

http://iolanguage.org/

http://iolanguage.org/scm/io/docs/IoGuide.html

--

also the Flask web page style looks nice:

http://flask.pocoo.org/

---

since we'll have standard documentation conventions in Oot, need to choose (or create) a std markup. Should look at reStructuredText, Markdown (w/ extensions MultiMarkdown?, Markdown Extra, Pandoc), WikiCreole?, AsciiDoc?, and of course EasyLatex?!

--

use the Haskell 'xs' convention for list variables (i.e. variables which hold lists end with 's')

--