Lisp project sites don't provide enough information - Lisp Propulsion Laboratory log

Lisp project sites don't provide enough information

I hesitate to critique free resources, especially when the prolificity of their authors is in sharp contrast with my limited contributions. But since Gary King publicly acknowledges information problems about his own Lisp software, I will chime in with a constructive spirit[*].

I have been submitting entries to the Common Lisp Directory since early 2006. CLD is a database of Common Lisp software and other resources.

I try to include in CLD entries as much information as possible about projects. This is to help users understand what a particular software project does, which Lisp implementations it runs on, which libraries are required, where to get the code, and evaluate the resource to decide whether it fits his needs.

But I frequently run across projects that don't prominently--or at all--provide one or more of the following information, all of which is important:

the names of authors or maintainers, or even screen names/nicknames; at times there is no trace of author identification all over the source code and documentation files

what the software actually does , what problem it is supposed to solve; some descriptions are so cryptic that they are useless

, what problem it is supposed to solve; some descriptions are so cryptic that they are useless what Lisp implementation and operating system the software runs, has been tested, or is assumed to work on; this is among the most common missing pieces of information , and forces the user to dig the code for #+foo-lisp forms or impdep.lisp files to figure it

, and forces the user to dig the code for forms or files to figure it what libraries the software requires; ASDF-INSTALL takes care of this in many cases, but knowing in advance which libraries the software relies on may help the user understand whether the program is able to run with his setup

some kind of information on the project status, such as a version number or date of the latest release; knowing dates is particular important, for example, for assessing whether a program is still likely to run on current implementations; and gives an indication on whether the project is still active

links to download a tarball with the latest version, or to a browsable version of the source code repository, when available; the latter is particularly useful for checking the quality and completeness of the code, assessing the project status, or studying the code for useful tricks or techniques

licensing information; many are nervous about using code with unknown distribution conditions

I don't think that the missing information is due to lack of time. Rather, I think that authors take too much for granted, and have difficulties in getting in the shoes of users and understanding their needs.

Actually, the web sites of Gary King's many useful Lisp projects do provide this information. The only headaches I had, as mentioned in his blog entry, are with dependencies. His software heavily relies on libraries with complex dependencies, at times apparently circular. Now I understand why you often find "meta" in his project names :-)

You may note that the information I discussed matches the fields of CLD entries. Indeed, we spend some time with each project entry and dig its source code or web site so that you don't have to.

Finally, this is problem is common to all free software, but Lisp projects have specific informational needs.