# Frustrated with the documentation

**URL:** <https://discourse.ats-lang.org/t/frustrated-with-the-documentation/239>\
**Category:** Google Group\
**Created:** [July 17, 2014, 12:41am UTC](https://discourse.ats-lang.org/t/frustrated-with-the-documentation/239 "2014-07-17T00:41:30Z")\
**Posts on this page:** 8\
**Page:** 1

<div class="post-metadata">

**Author:** ![Raoul\_Duke](https://avatars.discourse-cdn.com/v4/letter/r/bbe5ce/32.png) [@Raoul\_Duke](https://discourse.ats-lang.org/u/Raoul_Duke)\
**Post date:** [July 17, 2014, 12:41am UTC](https://discourse.ats-lang.org/t/frustrated-with-the-documentation/239/1 "2014-07-17T00:41:30Z")

</div>

frankly there are too many random disparate official places with  
information about ats. most of the time i cannot find what i want.  
even if i know i’ve seen it before. this is, i think, clearly an  
impediment to adoption by new people.

also i suspect there isn’t enough documentation. but it is hard to  
know what is / not covered because i cannot see the sum total of  
documentation easily.

please find a way to coalesce things. 🙂 this is not just a  
nice-to-have if you want it to be more than an academic language.

$0.02

(in particular, i’m just trying to learn about ats/2 templates…)

---

<div class="post-metadata">

**Author:** ![Brandon\_Barker](https://sea1.discourse-cdn.com/flex019/user_avatar/discourse.ats-lang.org/brandon_barker/32/61_2.png) [@Brandon\_Barker](https://discourse.ats-lang.org/u/Brandon_Barker)\
**Post date:** [July 17, 2014, 1:47am UTC](https://discourse.ats-lang.org/t/frustrated-with-the-documentation/239/2 "2014-07-17T01:47:33Z")

</div>

AFAIK, the only official places are the documents linked on this page  
[http://www.ats-lang.org/DOCUMENT/](http://www.ats-lang.org/DOCUMENT/)

Or are you referring to something else?

Brandon Barker  
brandon…@gmail.comOn Wed, Jul 16, 2014 at 8:41 PM, Raoul Duke [rao...@gmail.com](mailto:rao...@gmail.com) wrote:

> frankly there are too many random disparate official places with  
> information about ats. most of the time i cannot find what i want.  
> even if i know i’ve seen it before. this is, i think, clearly an  
> impediment to adoption by new people.
> 
> also i suspect there isn’t enough documentation. but it is hard to  
> know what is / not covered because i cannot see the sum total of  
> documentation easily.
> 
> please find a way to coalesce things. 🙂 this is not just a  
> nice-to-have if you want it to be more than an academic language.
> 
> $0.02
> 
> (in particular, i’m just trying to learn about ats/2 templates…)
> 
> –  
> You received this message because you are subscribed to the Google Groups  
> “ats-lang-users” group.  
> To unsubscribe from this group and stop receiving emails from it, send an  
> email to [ats-lang-user...@googlegroups.com](mailto:ats-lang-user...@googlegroups.com).  
> To post to this group, send email to [ats-lan...@googlegroups.com](mailto:ats-lan...@googlegroups.com).  
> Visit this group at [http://groups.google.com/group/ats-lang-users](http://groups.google.com/group/ats-lang-users).  
> To view this discussion on the web visit  
> [https://groups.google.com/d/msgid/ats-lang-users/CAJ7XQb521QnRFHA%3DFMVUdut42HrvUJRPcPA%3D%3DtPVkBBEGsfc1g%40mail.gmail.com](https://groups.google.com/d/msgid/ats-lang-users/CAJ7XQb521QnRFHA%3DFMVUdut42HrvUJRPcPA%3D%3DtPVkBBEGsfc1g%40mail.gmail.com)  
> .

---

<div class="post-metadata">

**Author:** ![gmhwxi](https://avatars.discourse-cdn.com/v4/letter/g/67e7ee/32.png) [@gmhwxi](https://discourse.ats-lang.org/u/gmhwxi)\
**Post date:** [July 17, 2014, 2:29am UTC](https://discourse.ats-lang.org/t/frustrated-with-the-documentation/239/3 "2014-07-17T02:29:48Z")

</div>

> > frankly there are too many random disparate official places with  
> > information about ats. most of the time i cannot find what i want.  
> > even if i know i’ve seen it before. this is, i think, clearly an  
> > impediment to adoption by new people.

For of all, ATS is a very rich and complex language. Documenting it  
properly requires a huge effort that is simply beyond what I can do on  
my own. I hope that a community of people will find it interesting to  
contribute to this effort.

> > frankly there are too many random disparate official places with  
> > information about ats. most of the time i cannot find what i want.  
> > even if i know i’ve seen it before. this is, i think, clearly an  
> > impediment to adoption by new people.

I suggest to start with the following book:

[http://www.ats-lang.org/DOCUMENT/ATS2TUTORIAL/HTML/book1.html](http://www.ats-lang.org/DOCUMENT/ATS2TUTORIAL/HTML/book1.html)

In particular, I suggest to try the examples in the book by typing in them  
one-by-one. In this way, you can get a good feel as to what type-error  
messages  
look like.

If you want to write code in ATS to solve realistic problems, please first  
have a good understanding about the ways in which ATS and C can interact.

Also, feel free to raise questions in this group.On Wednesday, July 16, 2014 8:41:50 PM UTC-4, Raoul Duke wrote:

> frankly there are too many random disparate official places with  
> information about ats. most of the time i cannot find what i want.  
> even if i know i’ve seen it before. this is, i think, clearly an  
> impediment to adoption by new people.
> 
> also i suspect there isn’t enough documentation. but it is hard to  
> know what is / not covered because i cannot see the sum total of  
> documentation easily.
> 
> please find a way to coalesce things. 🙂 this is not just a  
> nice-to-have if you want it to be more than an academic language.
> 
> $0.02
> 
> (in particular, i’m just trying to learn about ats/2 templates…)

---

<div class="post-metadata">

**Author:** ![Raoul\_Duke](https://avatars.discourse-cdn.com/v4/letter/r/bbe5ce/32.png) [@Raoul\_Duke](https://discourse.ats-lang.org/u/Raoul_Duke)\
**Post date:** [July 17, 2014, 6:22pm UTC](https://discourse.ats-lang.org/t/frustrated-with-the-documentation/239/4 "2014-07-17T18:22:52Z")

</div>

everybody is missing the point / i did a bad job making my point. apologies.

i do not just want new pointers to things: i desire for the current  
mish-mash to be cleaned up so that people never have to _ask_ such  
questions because they managed to find things relatively quickly and  
easily on their own.

somebody who doesn’t know ats or who is trying to find specific docs  
(e.g. i still haven’t found anything sufficient about templates!?!!!)  
ends up with google search results that are just all over the place -  
many different domains have stuff from the author of ATS himself, let  
alone all the other (2 or 3) places that are do-gooders trying to blog  
/ document more stuff about the language.

so basically there is no way to win: the official docs seem to not  
help, and google searching just makes it look like everything is a  
mess.

this is not the kind of user experience that will really help draw in new users.

i urge people who have control of the ‘official’ stuff that is out  
there to do things to rectify this **if they actually want the  
language to gain traction**. i mean, i’m offering this advice for free  
or you can go pay $$$ to some web marketing genius to get similar  
comments (but only if they are actually good). 🙂

[all this can probably done in the course of a week at least as a  
quick and dirty first pass of coalescing things. heck you might be  
able to get a Technical Writer / SEO type undergraduate to do this  
work in exchange for some credit, no?]

(a) have at most 2 places: github & then some core official ats docs site.  
(b) remove everything else anywhere else official (i’m not saying  
bluishcoder et. al. sites must die, far from it! only the disparate  
’official’ looking stuff). get rid of sourceforge for crying out loud.  
© how many different mailing lists are there, anyway? google?  
sourceforge? mailman? others? whittle them down as much as possible.  
(d) i believe the documentation should be restructured. my off the  
cuff suggestion is to have only the current version showing up at the  
"root" of the docs / on the home page. then the others can be  
available but off the main page.  
(e) is there a formal language spec anywhere? that would be good to  
have as a first link. that way while the informal documentation is  
catching up over time, at least somebody has a way to find _some_  
answer even if it is technically over their head 🙂

that’s what i think would minimally be good to staunch the problems i  
see. after that, more iterations can be done to further improve.

$0.02

---

<div class="post-metadata">

**Author:** ![Brandon\_Barker](https://sea1.discourse-cdn.com/flex019/user_avatar/discourse.ats-lang.org/brandon_barker/32/61_2.png) [@Brandon\_Barker](https://discourse.ats-lang.org/u/Brandon_Barker)\
**Post date:** [August 16, 2014, 10:34pm UTC](https://discourse.ats-lang.org/t/frustrated-with-the-documentation/239/5 "2014-08-16T22:34:19Z")

</div>

Well, here’s a new version of the website. It may need a few additions and  
color changes but otherwise I think it is basically perfect:  
[http://www.wonder-tonic.com/geocitiesizer/content.php?theme=2&music=11&url=www.ats-lang.org/](http://www.wonder-tonic.com/geocitiesizer/content.php?theme=2&music=11&url=www.ats-lang.org/)

Brandon Barker  
brandon…@gmail.comOn Thu, Jul 17, 2014 at 2:22 PM, Raoul Duke [rao...@gmail.com](mailto:rao...@gmail.com) wrote:

> everybody is missing the point / i did a bad job making my point.  
> apologies.
> 
> i do not just want new pointers to things: i desire for the current  
> mish-mash to be cleaned up so that people never have to _ask_ such  
> questions because they managed to find things relatively quickly and  
> easily on their own.
> 
> somebody who doesn’t know ats or who is trying to find specific docs  
> (e.g. i still haven’t found anything sufficient about templates!?!!!)  
> ends up with google search results that are just all over the place -  
> many different domains have stuff from the author of ATS himself, let  
> alone all the other (2 or 3) places that are do-gooders trying to blog  
> / document more stuff about the language.
> 
> so basically there is no way to win: the official docs seem to not  
> help, and google searching just makes it look like everything is a  
> mess.
> 
> this is not the kind of user experience that will really help draw in new  
> users.
> 
> i urge people who have control of the ‘official’ stuff that is out  
> there to do things to rectify this **if they actually want the  
> language to gain traction**. i mean, i’m offering this advice for free  
> or you can go pay $$$ to some web marketing genius to get similar  
> comments (but only if they are actually good). 🙂
> 
> [all this can probably done in the course of a week at least as a  
> quick and dirty first pass of coalescing things. heck you might be  
> able to get a Technical Writer / SEO type undergraduate to do this  
> work in exchange for some credit, no?]
> 
> (a) have at most 2 places: github & then some core official ats docs site.  
> (b) remove everything else anywhere else official (i’m not saying  
> bluishcoder et. al. sites must die, far from it! only the disparate  
> ‘official’ looking stuff). get rid of sourceforge for crying out loud.  
> (c) how many different mailing lists are there, anyway? google?  
> sourceforge? mailman? others? whittle them down as much as possible.  
> (d) i believe the documentation should be restructured. my off the  
> cuff suggestion is to have only the current version showing up at the  
> “root” of the docs / on the home page. then the others can be  
> available but off the main page.  
> (e) is there a formal language spec anywhere? that would be good to  
> have as a first link. that way while the informal documentation is  
> catching up over time, at least somebody has a way to find _some_  
> answer even if it is technically over their head 🙂
> 
> that’s what i think would minimally be good to staunch the problems i  
> see. after that, more iterations can be done to further improve.
> 
> $0.02
> 
> –  
> You received this message because you are subscribed to the Google Groups  
> “ats-lang-users” group.  
> To unsubscribe from this group and stop receiving emails from it, send an  
> email to [ats-lang-user...@googlegroups.com](mailto:ats-lang-user...@googlegroups.com).  
> To post to this group, send email to [ats-lan...@googlegroups.com](mailto:ats-lan...@googlegroups.com).  
> Visit this group at [http://groups.google.com/group/ats-lang-users](http://groups.google.com/group/ats-lang-users).  
> To view this discussion on the web visit  
> [https://groups.google.com/d/msgid/ats-lang-users/CAJ7XQb64aHR%2BPjN9%2B61PoWOGMXBLmf75GV1p9aG97hj2FPOgSg%40mail.gmail.com](https://groups.google.com/d/msgid/ats-lang-users/CAJ7XQb64aHR%2BPjN9%2B61PoWOGMXBLmf75GV1p9aG97hj2FPOgSg%40mail.gmail.com)  
> .

---

<div class="post-metadata">

**Author:** ![Brandon\_Barker](https://sea1.discourse-cdn.com/flex019/user_avatar/discourse.ats-lang.org/brandon_barker/32/61_2.png) [@Brandon\_Barker](https://discourse.ats-lang.org/u/Brandon_Barker)\
**Post date:** [July 17, 2014, 2:46am UTC](https://discourse.ats-lang.org/t/frustrated-with-the-documentation/239/6 "2014-07-17T02:46:09Z")

</div>

Very nice, last I checked, I didn’t notice ATS on rosettacode.

Brandon Barker  
brandon…@gmail.comOn Wed, Jul 16, 2014 at 10:42 PM, Chris Double [chris....@double.co.nz](mailto:chris....@double.co.nz) wrote:

> For learning languages ‘cookbook’ style I’ve found the following  
> useful for picking up other languages:
> 
> [http://pleac.sourceforge.net/](http://pleac.sourceforge.net/)  
> [http://rosettacode.org/wiki/Category:ATS](http://rosettacode.org/wiki/Category:ATS)
> 
> Interested parties might like to look at adding ATS ports for some of  
> the missing examples. These are good for looking up how to perform  
> tasks rather than learning about particular features though.
> 
> –  
> [http://www.bluishcoder.co.nz](http://www.bluishcoder.co.nz)
> 
> –  
> You received this message because you are subscribed to the Google Groups  
> “ats-lang-users” group.  
> To unsubscribe from this group and stop receiving emails from it, send an  
> email to [ats-lang-user...@googlegroups.com](mailto:ats-lang-user...@googlegroups.com).  
> To post to this group, send email to [ats-lan...@googlegroups.com](mailto:ats-lan...@googlegroups.com).  
> Visit this group at [http://groups.google.com/group/ats-lang-users](http://groups.google.com/group/ats-lang-users).  
> To view this discussion on the web visit  
> [https://groups.google.com/d/msgid/ats-lang-users/CALn1vHHg35MC1a%2BeU3OLxCQA9zuxAxhie-4p1pkeK%3D7r3OZJiA%40mail.gmail.com](https://groups.google.com/d/msgid/ats-lang-users/CALn1vHHg35MC1a%2BeU3OLxCQA9zuxAxhie-4p1pkeK%3D7r3OZJiA%40mail.gmail.com)  
> .

---

<div class="post-metadata">

**Author:** ![gmhwxi](https://avatars.discourse-cdn.com/v4/letter/g/67e7ee/32.png) [@gmhwxi](https://discourse.ats-lang.org/u/gmhwxi)\
**Post date:** [July 17, 2014, 5:29am UTC](https://discourse.ats-lang.org/t/frustrated-with-the-documentation/239/7 "2014-07-17T05:29:29Z")

</div>

Good.

I have just updated the existing ATS-examples at rosettacode to  
make sure that they can run under ATS2. There is no need to add  
ATS1-examples anymore.On Wednesday, July 16, 2014 10:42:51 PM UTC-4, Chris Double wrote:

> For learning languages ‘cookbook’ style I’ve found the following  
> useful for picking up other languages:
> 
> [http://pleac.sourceforge.net/](http://pleac.sourceforge.net/)  
> [http://rosettacode.org/wiki/Category:ATS](http://rosettacode.org/wiki/Category:ATS)
> 
> Interested parties might like to look at adding ATS ports for some of  
> the missing examples. These are good for looking up how to perform  
> tasks rather than learning about particular features though.
> 
> –  
> [http://www.bluishcoder.co.nz](http://www.bluishcoder.co.nz)

---

<div class="post-metadata">

**Author:** ![Raoul\_Duke](https://avatars.discourse-cdn.com/v4/letter/r/bbe5ce/32.png) [@Raoul\_Duke](https://discourse.ats-lang.org/u/Raoul_Duke)\
**Post date:** [August 17, 2014, 6:34am UTC](https://discourse.ats-lang.org/t/frustrated-with-the-documentation/239/8 "2014-08-17T06:34:47Z")

</div>

those spinning gifs!!!