search

ocaml / v2.ocaml.org

Implementation of the ocaml.org website.
http://ocaml.org
Other
322 stars 345 forks source link

Consider scrapping majority of current FAQ #236

Open yminsky opened 11 years ago

yminsky commented 11 years ago

This is perhaps a contentious suggestions, but the current FAQ seems pretty messy. It has some out of date suggestions (Num is basically deprecated, and people should probably use zarith instead), some that seem out of place in a FAQ ("how to define an enumerated type" seems like a better topic for a tour of the language, rather than an FAQ), lots of little grammatical mistakes, ("How to define multidimensional arrays" should probably be something like "How do you define a multideminsional array?", or "Types definitions" should be "Type definitions".

All told, the FAQ seems long and not of very high quality. I'd recommend starting from an empty page and pulling in FAQs from the list that seem good, rather than the other way around.

avsm commented 11 years ago

I agree with this. I'm happy to help draft questions when I get back to Cambridge next week if there's a general desire to do this...

On 11 Nov 2013, at 11:54, Yaron Minsky notifications@github.com wrote:

This is perhaps a contentious suggestions, but the current FAQ seems pretty messy. It has some out of date suggestions (Num is basically deprecated, and people should probably use zarith instead), some that seem out of place in a FAQ ("how to define an enumerated type" seems like a better topic for a tour of the language, rather than an FAQ), lots of little grammatical mistakes, ("How to define multidimensional arrays" should probably be something like "How do you define a multideminsional array?", or "Types definitions" should be "Type definitions".

All told, the FAQ seems long and not of very high quality. I'd recommend starting from an empty page and pulling in FAQs from the list that seem good, rather than the other way around.

— Reply to this email directly or view it on GitHub.

agarwal commented 11 years ago

The FAQ section of the site has never been good. It was an experimental section that we were hoping would get better through contributions, which never happened. I'm happy to scrap it completely.

avsm commented 11 years ago

Got it; I'll chat with @samoht and @altgr about an OPAM section there too -- there are a common emerging set of 'workflow questions' emerging that would be perfect here.

On 11 Nov 2013, at 12:02, Ashish Agarwal notifications@github.com wrote:

The FAQ section of the site has never been good. It was an experimental section that we were hoping would get better through contributions, which never happened. I'm happy to scrap it completely.

— Reply to this email directly or view it on GitHub.

agarwal commented 11 years ago

We could create a separate faq branch and start adding there. If it gets into shape, we can merge it in. In the mean time, there won't be a poorly maintained section live.

avsm commented 11 years ago

Does a "why ocaml" page fit into the FAQ? There are a number of articles such as: http://roscidus.com/blog/blog/2013/06/09/choosing-a-python-replacement-for-0install/

which would be good to link to from one place. It's certainly a frequently asked question, but may be better as a dedicated page.

agarwal commented 11 years ago

I think of FAQs as questions that can be answered in at most a paragraph or two. "Why OCaml" sounds like a whole page to me. We could have a long essay and also link to external articles.

On Mon, Nov 11, 2013 at 8:58 PM, Anil Madhavapeddy <notifications@github.com

wrote:

Does a "why ocaml" page fit into the FAQ? There are a number of articles such as:

http://roscidus.com/blog/blog/2013/06/09/choosing-a-python-replacement-for-0install/

which would be good to link to from one place. It's certainly a frequently asked question, but may be better as a dedicated page.

— Reply to this email directly or view it on GitHubhttps://github.com/ocaml/ocaml.org/issues/236#issuecomment-28261683 .

yminsky commented 11 years ago

For what it's worth, RWO has a "why ocaml" essay at the beginning:

https://realworldocaml.org/v1/en/html/prologue.html

On Mon, Nov 11, 2013 at 9:14 PM, Ashish Agarwal notifications@github.comwrote:

I think of FAQs as questions that can be answered in at most a paragraph or two. "Why OCaml" sounds like a whole page to me. We could have a long essay and also link to external articles.

On Mon, Nov 11, 2013 at 8:58 PM, Anil Madhavapeddy < notifications@github.com

wrote:

Does a "why ocaml" page fit into the FAQ? There are a number of articles such as:

http://roscidus.com/blog/blog/2013/06/09/choosing-a-python-replacement-for-0install/

which would be good to link to from one place. It's certainly a frequently asked question, but may be better as a dedicated page.

— Reply to this email directly or view it on GitHub< https://github.com/ocaml/ocaml.org/issues/236#issuecomment-28261683> .

— Reply to this email directly or view it on GitHubhttps://github.com/ocaml/ocaml.org/issues/236#issuecomment-28262402 .