Documentation

[mrkkrp]

Where is the proper documentation? babel.texi contains mainly

Bla bla bla, bla bla bla.

[luismbo]

Luís from 2007 called. He says he's really sorry, but he couldn't finish the documentation in time.

[mrkkrp]

I hope you told him that he still has 8 years to write the docs. I cannot ask you to write the docs, of course. Most probably, I can use your library on basic level without reading any docs. I can see your code and figure out many things. Yes, this is true, but it will be more difficult for me and it will take more time.

"Babel comes with converters between strings and (unsigned-byte 8) vectors but can be easily extended to deal with, e.g., strings and foreign memory, vectors and Closure's runes, etc..."

What if one would like to extend the library? You know how your library works, you can save time of many people. Yes, it will take your own time, but if you think about overall effect, not egoistically (yes, it's extremely difficult for some people), you will see that good documentation will remove duplication of effort for everyone who wants to use all features of your library.

The tendency of missing docs even for fairy complex projects shows how people don't consider their free software projects as a contribution to society, but as an egoistic whim that other people will use because they have no time to write every library themselves. I can see the logic "I put here the code, use it and say thanks that you don't have to write it yourself", well, it's fair, but it's also says something about those who think so.

I have noticed that the best hackers, people who love their projects, usually write good docs. And their programs are more elegant too. They demonstrate their wit through the hacking, not through cynical answers to questions of people who want to fully explore potential of their projects.

[luismbo]

Sorry @mrkkrp, I was just trying to be funny! Anyway, maybe we can collaborate on proper documentation for Babel. What system would you use? Texinfo might be overkill. I like atdoc. (I've used it for this project.) I'm curious about the recent mgl-pax library too, maybe that's worth exploring. What's your opinion?

[sionescu]

I suggest also taking a look at Sphinx. There's a plugin for CL(cldomain), example here

[luismbo]

@sionescu that looks good. Will look into that.

[mrkkrp]

@luismbo, I would like to help you. I'm only familiar with texinfo (example), for small projects I just write descriptions of functions in README file (example). If you want to use some specific library, tell me and I will try to understand how to use it. I can describe all public symbols in babel for a start.

[Symbolics]

declet? Perhaps the best of both worlds, since it can generate texinfo.

[luismbo]

I'm not a big fan of javadoc-style documentation. I has its uses, but it's particularly ill-suited for Common Lisp.