Hi all, I have some suggestions about the Qi4j documentation. First of all I think it would be a good idea to shake our heads and think from scratch [shake head now].
Documentation today has evolved naturally with many steps taken here and there, and eventually some documentation has become outdated, incomplete or missing. I think a lot of open source projects have had and have that experience too. It's frustrating and reduces anybodys will to invest time in this cumbersome activity that doesn't seem to payoff anyway. The approach and mindset then becomes "Argh, what is the minimal we can do and still get it to work? Is there some quick way? Could an automated java docs extraction system do the job? etc." No need to say that it's also frustrating from the users perspective - a main contributing factor to devaluate the perception of Qi4j when you drop by :-( Hey, let's make it cool instead!!! I know you will shake your heads again [optional shake head], but what if we think it the other way around: "Qi4j has a cool documentation!" What would that be? If this was really something cool, then I believe it would be something that any of us would much more likely want to contribute to. This is not about quantity. Writing endless documentation in a non-cool way is wired as painful in our brains and something that will never get done. I think that a real show-stopper is the idea that "it has to be complete". Already there, the mind gets tired. Does it ring a bell? As a user, I would rather have a third, no - a tenth of the documentation if I knew where to find it and if I knew if it was up do date. Every broken link or too late realization that the advice is outdated turns me off whereas "hm, not much documentation they have here, but it looks pretty cool" will let me continue exploring... So, if we instead start from above and think out loud "what would be the best way to do it?" and start collecting ideas of how it "should be", then we could get a good starting point to revise the website and documentation towards the cool system it should be. Okay, [shake head again] To make this a fun process, let's make it simple: 1) Let's collect links to websites that have any quality that we like - be it documentation, layout, menu system, download instructions - anything that is cool and that we have enjoyed using ourselves at some point. Let's not be intelligent or realistic at this point - just collecting links. Any link is welcome. 2) Then afterwards we can distill the ideas we want to pursue and start getting more "realistic" and think about implementation technologies and the lot. 3) Implement the technologies to use in order to get started. 4) Having fun putting in bits and pieces of documentation here and there in our new cool system. jQuery didn't get anywhere for a long time before they did this although it was a supercool system from the beginning too. For now, I suggest that we focus *only* on gathering some links to sites that have some feature or design that we could see as valuable on our Qi4j site. I'll start off with the following list (in no particular order): http://docs.jquery.com/Main_Page Great organization of content http://www.obdev.at/resources/launchbar/help/index.html Love the clean left menu http://wicket.apache.org/start/quickstart.html Easy way to start off a new project http://wiki.neo4j.org/content/Main_Page Reasonably good overview http://framework.zend.com/manual/en/ Nice versioning of documentation Sites you have enjoyed: _______________________________________________ qi4j-dev mailing list [email protected] http://lists.ops4j.org/mailman/listinfo/qi4j-dev
