|
That's only valid if you know the information that needs to be
introduced. I don't know anything about Kepler, which is where my complaint
stems from (that this isn't rectifiable with what the site
provides).
Maybe I'll be more able to contribute after reading the
chapter on it in my copy of Lua Programming Gems (which seems much better laid
out) which was delivered yesterday.
Sent: Thursday, October 15, 2009 P12:59
Newsgroups: gmane.comp.lang.lua.general
Subject: Re: Kepler cleanup
It's ironic how many open software projects today have wiki-based websites
but they miss the point of how a wiki works (wikipedia and c2.com still do it right). Should a wiki had been open
for anybody to write (yes, without login or subscription or asking email or
everything!), maybe your time would have been better served -- you might have
shown us a little on how to do it right instead of writing this long critique
:)
On Thu, Oct 15, 2009 at 21:41, Stuart P.Bentley <stuart@testtrack4.com>
wrote:
The site for Kepler needs to be majorly refactored. To a new
visitor to the site, it is completely impenetrable, and the disorganization of
the site reflects just as poorly on the project as a whole. Every sentence,
that is not directed toward current project developers, uses only the broadest
of terms rather than conveying an actual detail of the project. Several pages
that involve crucial information relating to starting with Kepler (such as how
to configure _any_ web server for actual use) openly lack even the most
rudimentary text, with the page for Xavante, the bundled server with Kepler,
being *completely blank*. Conversely, large sections of the site are devoted
to open-ended "puff piece" general topic questions such as "What is web
development?"
To start addressing the site's specific shortcomings as
it stands, the first line of the homepage is:
"Kepler is an open source
platform that brings the power of Lua to web development."
"Platform"?
It offers (from what I can piece together, at least) 3 separate, alternative,
and conflicting modules that bill themselves as the exact same thing. You can
develop "for Linux", "for iPhone", and even "for Lua": you can't develop "for
Kepler". Likewise, module documentations keep using terms like "abstraction",
"tool", and "framework", but they never contextualize it. .NET and Mediawiki
are both "frameworks", but you can't use .NET in place of Mediawiki or
vice-versa. These terms are complete non-descriptors in software development:
a programming language is an abstraction framework tool, and so is anything
written with it.
It then goes on to explain several tautologies, such
as asking the user, if they're familiar with Lua, to "think about all that
power applied to web scripting". If the user is familiar with Lua, they don't
need to be told that this power applies to web development if they've been
told that Kepler is the application of Lua to web development, or that using
Lua for web development allows you to use the modularization of Lua for web
development. It's like telling someone that "a tiger is a large cat" and then
following it by adding "if you've ever seen a cat move, a tiger moves like
that". People can figure out basic interrelationships such as these, and
listing them out only takes up space on the page while adding nothing, much
like this entire paragraph explaining tautologies.
If they're not
familiar with the advantages of Lua, they can get them in full from lua.org (one link that is prominently
absent from the site as a whole). The purpose of an overview is to explain
what the user has arrived at. If the site's target audience is assumed to
already be familiar with a topic it mentions in passing, it should provide a
link to an in-depth explanation (the topic's home page) for the edge scenario
where that's not the case.
|
