Date: 05 Apr 2002 10:57:13 -0800 From: swear@blarg.net (Gary W. Swearingen) To: Antoine Beaupre <anarcat@anarcat.ath.cx> Cc: freebsd-libh@FreeBSD.org Subject: Re: libh learning curve, etc. Message-ID: <siadsi2cty.dsi@localhost.localdomain> In-Reply-To: <370BA4FE-48A2-11D6-945B-0050E4A0BB3F@anarcat.ath.cx> References: <370BA4FE-48A2-11D6-945B-0050E4A0BB3F@anarcat.ath.cx>
next in thread | previous in thread | raw e-mail | index | archive | help
Antoine Beaupre <anarcat@anarcat.ath.cx> writes: > If you ever worked on a already-started project, you would know that > it's much harder to document and promote code that's already written. Nobody expects detailed source code documentation. Almost no free software has that. But some current (and prospective) high-level documents would benefit the project. Of course, I realize that many people join projects for reasons other than the benefit of the project, and I respect that, but it seemed clear that the -libh project was devoting almost none of its time to Public Relations and that sort of thing and very much needed to be "reminded about it" (as you put it). As a former Linux web index maintainer, I've seen a lot of project web sites, and think I have a feel for their importance to the project. (No evidence, but a feel, nonetheless.) For instance, the early GNOME web site was a marvel of good, simple layout, covering all the bases and looking good without being flashy. And I suspect that it was responsible for encouraging the entry of many developers to the project. > I think it might be a good idea to put a tarball of a port snapshot on > the website thought. Good idea. And links to web sites for TVision and TCL and Qt (and to licenses to those and your own). And links to articles like the one JKH did last September for the 5.0 to-do list. People can use Google, like I did, but you should make it easy for them. Google returned 10 pages on "freebsd libh" but there were maybe 5 pages of good value. > > -- The CVSWEB tool at freebsd.org has only a few, uninteresting libh > > files. > > That's because libh is not part of the main freebsd CVS repository. There's a few files there. Enough to waste 10 or 15 minutes figuring it out. You should say on your website what you just told me. > > -- The mailing list archives are mostly mind-numbing commit messages. > > *That's* not constructive. Why not? I can envision a project with a separate list for such notices. > 1- get sponsorship > 2- get people to work on libh > > The problem with [1] is that noone seems to be interested in sponsoring > a tool so unimportant (!). And the problem with [2] is that we need to > work on documentation and design documents, and to get there, we need > [2]. From the looks of the list archives, you have some coders. I just wanted to remind them that you can generate more code by attracting more coders than you can by coding. Of course, personal purposes are a factor and you have to let yourselves spend most of your time doing what benefits yourself, not the project. But hopefully not 99.94% of it. > There was some good criticism, but I'm getting tired of seeing people > just pass by the page and say: "Hey, this looks like it needs some help, > let's complain to -libh@!". Yes the code is under-documented, yes, we > need some solid design documents. Thank you for reminding us. Forget about the code being under-documented. Document at a high level. Turn the JKH memo into a document that at least looks like it reflects the current design. Give people a few diagrams to look at. Etc. > I hope you'll take this as constructive criticism; it wasn't meant to > hurt feelings though it probably will. No hard feelings here; I expected a worse reaction and hesitated to cause it. But thought it worthwhile, even if it does damage my name before I've totally abandoned any plans to join the project. > Maybe I'm just ranting and I should shut up as I had the same reaction > as you the first time I got interested in libh. I'd say the project was very lucky to get someone as willing as you were to work past the reaction and work hard enough to learn whether you wanted to be a part of the project. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-libh" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?siadsi2cty.dsi>