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.
