Re: Getting Started with Lua

[Peter Cawley <lua@...>]

On Wed, Dec 21, 2011 at 11:11 PM, Luiz Henrique de Figueiredo
<lhf@tecgraf.puc-rio.br> wrote:
>> This seems just a repackaging of existing materials (about, faq, pil, wiki).
>
> That was my point. Does the site map, which has links to all those, suffice?
> Or does anyone actually look at the site map??

Firstly, I'd like to state that I think packaging can be very
important. The phase "just a repackaging" sounds rather derogatory,
but I don't think that it should (or at least, not always). If good
information cannot be found, or people don't realise that they are a
few clicks away from good information, or good information is scatted
over various pages in an unorganised manner, then said information
might as well not exist.

Secondly, I used to use the site map a lot, as I found the
organisation of pages into about / download / documentation headings
to be rather arbitrary. Nowadays I've memorised the URLs of all the
pages I commonly go to, and so I rarely use the navigation. Unlike
Petite, I don't (or at least didn't) find the Lua site simple to
navigate (and navigating by going directly to the URL rather than
using the links is probably a sign of this), though I do agree that
site maps should be deprecated in favour of decent navigation.

Compared to other programming language sites (e.g. haskell.org,
python.org), I find the Lua site to be very spartan. Perhaps this
reflects the philosophy of Lua, but I think that it may be too spartan
(again, the phrase "web 2.0 site" can often be derogatory, but there
must have been some advancements in web design in the last decade).
For example, the Python site has a nice little blurb (whereas an
equivalent blurb for Lua is hidden behind an "about" link), and the
Haskell site has a really obvious "Download Haskell" button, whereas
for Lua you need to follow the "download" link, then find the small
"Lua 5.2.0" link (which given the context of the link, I'd have
thought went to another page if it weren't for the .tar.gz extension
on the URL). Alternatively, following the "source" link goes to
http://www.lua.org/ftp/, which makes all the right visual cues for
download links, though I'd argue that files should be sorted by
descending version number rather than ascending version number, as I'd
expect more people to be looking for 5.2 than looking for 1.0.

Likewise, I find the Lua Users Wiki to be very spartan and rather
unfriendly in terms of navigation and style (conversely the content is
generally comprehensive and friendly). I'm veering even more off-topic
with this though, so I'll leave it there.

Like Gavin, I think that any "Getting Started" area is going to have
multiple distinct audiences. An experienced programmer seeing Lua for
the first time will want "The [C | Javascript | ...] coder's guide to
Lua syntax and semantics", followed by a link to the standard library
reference, or they might want "How to embed Lua into your [C | C++]
program, and why you might want to", followed by a link to the C API
reference. Conversely, inexperienced programmers probably want to be
pointed toward a particular embedding of Lua, be it Love2D, WoW
Addons, etc. There is probably a semi-experienced programmer group
somewhere between, and I'm not sure what would be best for them.