Documentation Site

[Hannes]

Hi Lifters,

I'm thinking about setting up a site that takes together all available
information about Lift (Links, News, ...).

I would like to know, if this would be appreciated or not. I still think
that all the available information is to much spread out - specially for
people who get started with Lift. In case of positive responds, I would
like to setup a Plone (CMS) site. I think its a really good tool, to
organize content.

thanks for listening.

[TylerWeir]

Why not improve the existing wiki on github?

Or fork the book and make improvements that way?

I'm not opposed to additional resources, but why create another place
where docs may or not be out of date?

I think that Lift is still at the point where one location of docs is
better.

My opinion.

[Hannes]

Definitely! I would like one location for everything, but I believe that the current situation is not like that.

- there two API docs 1.0 and 1.1, the latter is hard to find
- there's liftweb.net (a little bit out-dated)
- there's the Wiki
- there's David's Blog (that has some unique information)

What did I forget?

thanks.

--

You received this message because you are subscribed to the Google Groups "Lift" group.
To post to this group, send email to lif...@googlegroups.com.
To unsubscribe from this group, send email to liftweb+u...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/liftweb?hl=en.


  

[TylerWeir]

Why not help make the wiki the "one location?"

[Marius]

+1 for the wiki site being the official Lift documentation place. I'm
not sure if github should be the wiki "container" ... IMHO the
official Lift website should be.

Br's,
Marius

[Timothy Perrett]

1.0 is the last official release that was not a milestone or snapshot
- thus, they are the primary api docs right now until we release 2.0
(that is, what was being called 1.1 is being renamed to 2.0). API docs
are a process issue, and handled as part of our build process - they
will always live both on scala-tools and liftweb.net where applicable.
They wont ever sit anywhere else (officially).

Yes, the wiki is a little out dated. I forget the number of times i've
tried to spear head a wiki effort... the bottom line is that other
people need to start writing content - there are a fair number of
competent lift users in the community who simply are not giving
anything back by way of articles or wiki cleaning - thus our docs get
out dated fast because the team prefer to write code than
documentation. We even tried to appointed a wiki gardener but he
appears to have just disappeared into the ether... Id be open to
hearing suggestions on how one could keep the wiki more up to date?
Short of users actually contributing back, there is a limit on what
the team can do at anyone time. We are getting there, but its not
going to be an overnight process.

Blogs - a fundamental corner stone of the internet and your right,
they are a great information repository. Perhaps we could syndicate
some blogs onto liftweb.net during the rewrite (yes, im going to
rewrite it at last!)... certainly open for that.

Cheers, Tim

PS: Sorry that was a bit of a rant, but this is a frustrating issue
that i've been pushing for over a year ;-)

[Hannes]

Hi Tim,

Thanks for your reply.

1.0 is the last official release that was not a milestone or snapshot
- thus, they are the primary api docs right now until we release 2.0
(that is, what was being called 1.1 is being renamed to 2.0). API docs
are a process issue, and handled as part of our build process - they
will always live both on scala-tools and liftweb.net where applicable.
They wont ever sit anywhere else (officially).
  

I just mentioned the API docs, because some time ago I was on the look for something I couldn't find in the 1.0 docs and than I had real problems to find the link for the 1.1 docs.

Yes, the wiki is a little out dated. I forget the number of times i've
tried to spear head a wiki effort... the bottom line is that other
people need to start writing content - there are a fair number of
competent lift users in the community who simply are not giving
anything back by way of articles or wiki cleaning - thus our docs get
out dated fast because the team prefer to write code than
documentation. We even tried to appointed a wiki gardener but he
appears to have just disappeared into the ether... Id be open to
hearing suggestions on how one could keep the wiki more up to date?
Short of users actually contributing back, there is a limit on what
the team can do at anyone time. We are getting there, but its not
going to be an overnight process.

  

Actually I didn't used the Lift Wiki so much, because in general I don't like the Media Wiki content organization so much. I think (my personal opinion) there are to much links and sometimes its hard to see which ones belong to the Media Wiki functionality itself and which ones are actually representing the "interesting" stuff. I think this was one of the major reasons why I didn't applied as a Wiki gardener.

Blogs - a fundamental corner stone of the internet and your right,
they are a great information repository. Perhaps we could syndicate
some blogs onto liftweb.net during the rewrite (yes, im going to
rewrite it at last!)... certainly open for that.
  

Maybe some idea would be to setup liftweb.net with some CMS and first re-arrange and update the content there and than, as a second run, include Blogs, the Wiki and "easy to find" links for the API docs.

Besides that, another problem with Media Wiki is, that it doesn't provide all the functionality, that this project needs and because of this, at least one other application is needed to deal with the rest. A CMS can do a lot and there are a lot of plug-ins available  for all kinds of stuff (a lot of stuff that doesn't need to be re-invented). And I believe that one system is easier to handle than three different ones.

Like I said before, just my opinion and an idea.

Cheers, Tim

PS: Sorry that was a bit of a rant, but this is a frustrating issue
that i've been pushing for over a year ;-)

  

thanks.

[Randinn]

To give the benefit of doubt to people who use Lift knowing that is
closed to commiting they may think the same about the documentation. I
have added a bit but I've more thrown up a few pages and figured
someone with more knowledge would flesh them out.

[Timothy Perrett]

I really don't think thats the issue - Lift is not "closed to committing"... if that were the case, David would never have recruited us onto the team ;-)

95% of all OSS projects i've ever come across have the same policy when it comes to wikis etc... they are organic, community driven beasts. For instance, I was no aware that you had written any articles... but that is great. You say you want them fleshed out? In what way / what information do you need.

Writing documentation is actually a great way to understand something because it means you have to fully grok it in order to teach others - we need to solve the documentation issue for sure, and any contribution you or others have is very much welcome.

Cheers, Tim

[johncch]

Well, this is an apt discussion at this point in time I feel. One of
the weakness of the Lift Project is really the sparse documentation,
as well as the rapid cycle of development obsoleting virtually many of
the slightly older code out there.

I don't mind contributing my time improving the documentation. Perhaps
one of the reasons why people don't contribute back is that the wiki
is not very prominent, for one reason or another. It's just rarely
referenced anywhere else most of the time. Would appreciate a more
concentrated effort on this.

I haven't actually seen the lift 1.1 scala docs. For example,
http://www.scala-tools.org/mvnsites-snapshots/liftweb/lift-base/lift-common/scaladocs/index.html
points to a blank page - that's for Lift common. I mostly rely on the
IDE(idea) to open up declarations via maven.. not exactly the best
method since the source code is more often than not not commented.

The lift framework is pretty massive, I think that's the reason why
it's difficult to write comprehensive documentation for it. I'm just
wondering what is a good way to go about doing that? A list of how-tos
plus in depth discussion about each part of the framework i.e. base,
or common, or? Perhaps there can be one page for every logical object
in Lift.

regards,
CH

[Randinn]

Well for the current information the places to go are
http://scala-tools.org/mvnsites-snapshots/liftweb/index.html and
http://wiki.github.com/dpp/liftweb if that will help you.

On Dec 21, 7:47 pm, johncch <john...@gmail.com> wrote:
> Well, this is an apt discussion at this point in time I feel. One of
> the weakness of the Lift Project is really the sparse documentation,
> as well as the rapid cycle of development obsoleting virtually many of
> the slightly older code out there.
>
> I don't mind contributing my time improving the documentation. Perhaps
> one of the reasons why people don't contribute back is that the wiki
> is not very prominent, for one reason or another. It's just rarely
> referenced anywhere else most of the time. Would appreciate a more
> concentrated effort on this.
>

> I haven't actually seen the lift 1.1 scala docs. For example,http://www.scala-tools.org/mvnsites-snapshots/liftweb/lift-base/lift-...