I've only just started looking into Lift, and my first impression is the documentation needs some help. Since I am new, I'm hoping you will find this feedback as a potential common case for anyone evaluating the Lift web framework.
1. The "API Documentation" link on the liftweb.net home page points to the maven generated documentation, but there are no links to the scaladocs there that I can find. Maybe this is my inexperience with maven, but there doesn't appear to be much there as a whole. 2. The "StartingWithLift.pdf" document linked on the lift home page is good. I do have a few suggestions: - Simply copying and pasting the commands into the command line can be problematic. For example, when I tried to start the 'todo' tutorial, I ended up with the following. Notice that most of the pasted text has a space between each letter, and the hyphen character is not the ascii '-' but the unicode '-' (appears longer on my system). This same text in the "Exploring Lift" book doesn't appear to have this problem. mvn a r c h e t y p e : g e n e r a t e -U \ -DarchetypeGroupId=n e t . l i f t w e b \ -D a r c h e t y p e A r t i f a c t I d= l i f t -a r c h e t y p e -b a s i c \ -D a r c h e t y p e V e r s i o n =0.10 \ -D r e m o t e R e p o s i t o r i e s=h t t p : / / s c a l a -t o o l s . o r g / repo-r e l e a s e s \ -DgroupId=com . l i f t w o r k s h o p \ -D a r t i f a c t I d=todo \ -D v e r s i o n =0.1-SNAPSHOT - In general, I think it is good practice to have such documentation online in HTML format, particularly the quick-start and entry level docs. A PDF viewer isn't always installed on a system by default, and requiring it means there is one more software requirement before a new developer can get started. Granted, this is a fringe case. I wouldn't abandon a PDF format, and since the same material is available in the full "Exploring Lift" document, the more complete document could fill that purpose. - You may want to consider using page space more economically within the PDF doc. There is a lot of dead white space around the text. This can be useful for jotting down notes, but it also requires more paper when printing. Using more of the white space is good for both economical and ecological greenness. Granted, the StartingWithLift.pdf document isn't huge, but every little bit helps. 3. The wiki index page could benefit from some updates and reorganization. For example: - The unconference is over. The link points to David Pollak's blog (a good link to have), but is unrelated to the unconference. - The marketing-like text is located in two different places. The section comparing it to the various web frameworks at the start and the "Advanced Framework" section further down. - The getting started stuff should probably be near the top instead of being more than half way down the page. Those just starting should have the information they need practically jump out at them. - There is some redundant stuff on the wiki index page and the liftweb.net home page. If I've read it once, I don't need to read it again, unless more detail is provided or it is presented in a different angle (e.g. how to sell it to management). I would recommend leaving all the marketing stuff on the home page or create a separate "About Lift" page, and the wiki can focus on getting things done. This is particularly true since the liftweb.net home page appears to give the link to quotes greater visual importance than the API documentation or wiki links. 4. Is there some reason why the wiki cannot provide the "In Progress Book" in PDF or HTML format? It took me two attempts and only after a significant effort was I able to generate the PDF (Ubuntu has an older and incompatible version of lyx as default, and Windows had all kinds of install and performance issues due to my various security software). The lyx files are available under the Creative Commons License, so I would assume there isn't any legal restrictions. If network bandwidth is an issue, maybe a torrent link could be set up instead of hosting it directly (not ideal but better than nothing). I will say kudos on the book authors. I haven't had a chance to digest it yet, but my initial impression is it's just what I've been looking for. The long and the short of it is I felt like I needed to dig and jump through hoops to get to the best documentation available. All the information is there; it just isn't easily (or obviously) accessible with a few mouse clicks from the liftweb.net home page. I am a persistent guy, but I do like my immediate gratification. I am looking forward to getting my feet wet with Lift! --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Lift" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/liftweb?hl=en -~----------~----~----~----~------~----~------~--~---
