SeanTAllen
commented
7 years ago Hi @marshray all of these except for #4.
You can get the documentation offline, but you have to generate it yourself. You'd need mkdocs installed though. There's a make docs command that will create an mkdocs website. Do you think that would work for you?
marshray
We only get one chance to have first impressions so I am writing mine up in the hope you will find it valuable. Feel free to ignore, or let me know if you'd like me to split up any of these items into separate bugs.
I have a background in writing concurrent applications in C++ and some familiarity with actor systems and capabilities. I learned about Pony via the recent HN story on the Wallaroo product and have watched an hour or two about Pony on YouTube. I have been to ponylang.org a few times and done some background reading.
Some simple things that will make my life easier at this point in my Pony journey:
A link to the download and install instructions directly from the home page. A simple text search did not find the words 'download' or 'install' anywhere on the home page, the "Learning Pony?" page or the FAQ. [possible duplicate of #118]
A link to the nice tutorial directly from the home page. I've gotten ponyc installed and am visiting ponylang.org to start on that tutorial I remember reading about somewhere. I had the impression that a lot a of nice work had been put into that tutorial and I expected it to be featured rather prominently from the main page. Hmm, I don't see it on the home page. I checked "New to Pony?" but do not see it there. I clicked "Learning Pony?" and I see options for 'getting help', 'getting started', and 'reference capabilities'. I do a text search for 'tutorial', OK there it is, but buried below-the-fold in the middle of a 3-screenful document.
A link to the current language and API reference documentation from the home page. I assume there is some, but I haven't found it yet. Update: from https://github.com/ponylang I found https://github.com/ponylang/stdlib.ponylang.org which had a link to https://stdlib.ponylang.org/ . This looks great, but I can't find anywhere on the main site that links to it.
A tar.gz or zip with the documentation for offline use. I know this is old-fashioined, but sometimes I work with poor connectivity or disconnected altogether. Also, this can be a requirement for high-security users. I downloaded the stdlib.ponylang.org repo, but all the links are broken when accessed via file://. (They seem to assume a webserver will redirect urls ending in / to index.html .)
There is a sort of informal grammar for supporting materials for open-source languages. I suspect many other potential users will be coming to Pony with expectations set by previous experience. Cf. https://www.python.org/ https://www.python.org/about/gettingstarted/ https://www.ruby-lang.org/en/
Thanks!