Docs: making documentation even more beginner/user-friendly

[justinek]

Comments on webPPL documentation, to be taken with a grain of salt!

Quick start

• Maybe the very first bullet should be, "If you haven't yet, install nodejs"?

  Usage

• In general, it might be helpful to accompany each line of code with a short note about when it would be useful to perform it. For example, when might one want to set a seed for the random number generator? When would it be useful to compile to Javascript?

  Inference

• How is EnumerateLikelyFirst different from the default heuristic of "most probable first"?
• It would be helpful to include more details on the different search strategies, a well as some rough guidelines on when each strategy should be used

  WebPPL packages

• It might be useful to include a brief description/reminder of the differences between WebPPL and regular JS, to make clear when packages are useful to work around certain limitations of WebPPL (e.g. immutability)
• Maybe include a note on when macros are useful?
• Under Javascript functions and libraries, there's a gentle warning that "Note that packages must export functions as properties of an object. Exporting functions directly will not work as expected." Maybe it would be useful to give an example of what works and what doesn't to make the correct usage even more clear?
• In the example for under "Additional header files," it was not immediately clear to me what k is.
• It might be helpful to include a bit more documentation for the package template, with information about what the package does and which parts should be changed to implement user's own package

[chrisranderson]

I have a draft for a new quick start page here: https://github.com/chrisranderson/webppl/blob/quick-start-rewrite/docs/quickstart.rst

@null-a, it's ready-ish but I'd like some input first. Is it better for me to just submit a PR or comment like this? Also, what do you think about the rewrite?

[longouyang]

That looks great to me. Could you also mention that installation requires git? (that is certainly true on Windows and I think it might be true of OS X / Linux too)

A typo: "help lin learning the syntax"

[chrisranderson]

How is git required?

On Wed, Jul 13, 2016, 7:13 PM Long Ouyang notifications@github.com wrote:

That looks great to me. Could you also mention that installation requires git? (that is certainly true on Windows and I think it might be true of OS X / Linux too)

A typo: "help _l_in learning the syntax"

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/probmods/webppl/issues/444#issuecomment-232530860, or mute the thread https://github.com/notifications/unsubscribe/AFNVlockDUQoCb5GHJTANOedSiyj9x8Eks5qVY0_gaJpZM4IjcvI .

[longouyang]

Some of our npm dependencies are github repos (e.g., probmods/sweet.js#browserify) -- when I tried installing on Windows without git, it choked when trying to set these up.

Also, I believe the webppl package system depends a little on running the git binary.