API documentation

[David Ashirov]

Hi all,
I have been reading this list since 2.3 release and scanned the message archives on occasion. I think I understand the challenges quite well, so please don't take this wrong.

It seems there are a few major themes  discussed here, one major topic being mostly routed in absence of good API documentation. Yes, books are helpful, so is the test suite. I think a more detailed API doc though, would be extremely helpful as well. Currently most of the doc is a simple list of classes and traits with no description of what they are there for or what do they intend to do.

Is there an effort underway to add clarity to API docs? How can I contribute?

[Peter Robinett]

Hi David,

The best and easiest way to contribute, I'd say, is to add and improve wiki pages. Thanks for the offer to help!

Peter

[David Ashirov]

I'd be more interested in getting API documentation up-to-date. Can I be involved with that instead? 

[Ben Phelan]

If I may be permitted to interject my ill-founded and poorly-formed thoughts on this topic, it seems to me the biggest issue WRT API documentation is Mr Pollack's exceptional code contribution policy (based on the number of times I've seen people offer to contribute to the API docs and the inevitable responses).

As both an enormous policy fan (we are currently going through tech audits and this policy is a nice checkbox) and frustrated outsider with little time to commit wholesale I often wonder whether there might be some possibility of streamlining the process or making certain portions of it more light-weight to enable and make it faster and easier for non-core contributors to contribute on occasion.  For example, there are FOSS projects that will accept changesets on Github so long as the commit message contains the correct agreements from the committer.  I really know very little about any of this though...

[David Pollak]

Please see this thread: https://groups.google.com/d/msg/liftweb/i2zT19MVkY0/pwlR70LT66kJ

On Wed, Oct 19, 2011 at 3:41 PM, Ben Phelan <bem...@gmail.com> wrote:

If I may be permitted to interject my ill-founded and poorly-formed thoughts on this topic, it seems to me the biggest issue WRT API documentation is Mr Pollack's exceptional code contribution policy (based on the number of times I've seen people offer to contribute to the API docs and the inevitable responses).

As both an enormous policy fan (we are currently going through tech audits and this policy is a nice checkbox) and frustrated outsider with little time to commit wholesale I often wonder whether there might be some possibility of streamlining the process or making certain portions of it more light-weight to enable and make it faster and easier for non-core contributors to contribute on occasion.  For example, there are FOSS projects that will accept changesets on Github so long as the commit message contains the correct agreements from the committer.  I really know very little about any of this though...

--
Lift, the simply functional web framework: http://liftweb.net
Code: http://github.com/lift
Discussion: http://groups.google.com/group/liftweb
Stuck? Help us help you: https://www.assembla.com/wiki/show/liftweb/Posting_example_code

--
Lift, the simply functional web framework http://liftweb.net

Simply Lift http://simply.liftweb.net
Follow me: http://twitter.com/dpp
Blog: http://goodstuff.im

[Ben Phelan]

Cool. :)