You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by "Tarek M. Nabil" <Ta...@itworx.com> on 2002/07/28 13:15:22 UTC
I need your advice
Hi everyone,
You might find this sort of strange, but I need your advice on whether I should get involved in this project or not.
I will state all the facts, and will wait for your opinion.
1- I'm not an experienced Java developer, my hands-on experience with Java, does not exceed 6 months.
2- I LOVE Java, though I don't get to work with it a lot, and I got certified as a java programmer a few months ago.
3- I've never participated in any open source projects.
4- If I do participate, I have to eventually get to the core of it, I cannot settle for supplying documentation or that sort of stuff.
5- The reason why I want to participate, is to get a chance to work with my favorite language and benefit from your experience.
5- I don't know a single thing about indexing, crawlers or search engines.
6- The reason I picked this project, is that I read on the new Jakarta newsletter that it's in need of developers.
I know this was kind of long, but it hope it will give you a clear picture.
Thanks in advance,
Tarek M. Nabil
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: Good Software/Documentation was Re: I need your advice
Posted by Clemens Marschner <cm...@lanlab.de>.
> <plea-for-validation>
> I get rated by the feedback I get from readers, so if you like
> the articles, please fill out the little form at the bottom.
> </plea-for-validation>
That's the kind of feedback we'd need for all our docs :-)
--Clemens
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: Good Software/Documentation was Re: I need your advice
Posted by Brian Goetz <br...@quiotix.com>.
> well said. I look forward to your article.
<shameless-self-promotion>
It will appear in the IBM Java Zone (www.ibm.com/java), in my "Java
Theory and Practice" column, in early September.
This month's column is on an obscure thread-safety issue, and next
month's is a very simple nuts and bolts of how and why to build a
thread pool. The next article? No ideas yet. If you've got any,
send 'em.
<plea-for-validation>
I get rated by the feedback I get from readers, so if you like
the articles, please fill out the little form at the bottom.
</plea-for-validation>
</shameless-self-promotion>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: Good Software/Documentation was Re: I need your advice
Posted by "Andrew C. Oliver" <ac...@apache.org>.
Brian Goetz wrote:
>>Is there any reason to believe that something along the lines of
>>literate programming will play a role in bridging the gap between
>>good software, bad documentation?
>>
>>
>
>I have reason to believe the opposite, sadly.
>
>Java made an attempt to pick up on some of the principles of LP when
>integrating JavaDoc into the source code. Unfortunately, the JavaDoc
>has replaced, rather than supplemented, external documentation, and
>most JavaDoc ranges from bad to worthless. And JavaDoc is really only
>for reference; its a _terrible_ way to actually learn an API, although
>that's how we all do it.
>
>I think the answer is cultural; ostracize and fire programmers that
>don't write documentation up to the level of their code. (OK, this is
>overstated by several notches, but you get the point.) When
>programmers become embarrassed if they write bad (or no)
>documentation, they'll write better documentation.
>
>
>
well said. I look forward to your article.
>--
>To unsubscribe, e-mail: <ma...@jakarta.apache.org>
>For additional commands, e-mail: <ma...@jakarta.apache.org>
>
>
>
>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: Good Software/Documentation was Re: I need your advice
Posted by Brian Goetz <br...@quiotix.com>.
> Is there any reason to believe that something along the lines of
> literate programming will play a role in bridging the gap between
> good software, bad documentation?
I have reason to believe the opposite, sadly.
Java made an attempt to pick up on some of the principles of LP when
integrating JavaDoc into the source code. Unfortunately, the JavaDoc
has replaced, rather than supplemented, external documentation, and
most JavaDoc ranges from bad to worthless. And JavaDoc is really only
for reference; its a _terrible_ way to actually learn an API, although
that's how we all do it.
I think the answer is cultural; ostracize and fire programmers that
don't write documentation up to the level of their code. (OK, this is
overstated by several notches, but you get the point.) When
programmers become embarrassed if they write bad (or no)
documentation, they'll write better documentation.
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Good Software/Documentation was Re: I need your advice
Posted by Jack Park <ja...@thinkalong.com>.
Brian,
Is there any reason to believe that something along the lines of literate
programming will play a role in bridging the gap between good software, bad
documentation?
Jack
At 11:53 AM 7/28/2002 -0700, Brian Goetz wrote:
> > 4- If I do participate, I have to eventually get to the core of it,
> > I cannot settle for supplying documentation or that sort of stuff.
>
>(response to the community, not just to you)
>
>If software engineering is ever to be taken seriously as an
>engineering discipline (like structural engineering, for example),
>we've got to ditch the collective attitude that documentation is
>something peripheral, or constitutes "settling." This is the same
>mistake that societally causes us to pay teachers less than
>bartenders, but as an educated bunch we shouldn't be making that
>same mistake.
>
>(Good timing, my next article on IBM's Java Zone is a rant on the thesis
> Good Code && Bad Documentation == Bad Code
>)
>
>To respond to Tarek, open-source communities are largely meritocratic.
>You'll be able to contribute to the "core" when (a) you've
>demonstrated that you contribute worthwhile stuff, and (b) you've got
>something to contribute that is useful to the community. Its pretty
>simple.
>
>Welcome!
>
>--
>To unsubscribe, e-mail: <ma...@jakarta.apache.org>
>For additional commands, e-mail: <ma...@jakarta.apache.org>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Jakarta docs // Re: I need your advice
Posted by Clemens Marschner <cm...@lanlab.de>.
May I add that the jakarta site structure doesn't really support good
documentation? I often find it very confusing. I often find myself on
jakarta-general pages when I expect to be on lucene pages. Docs for
different projects differ more than you would expect from the standardized
output format. No printable versions. etc. Most of the docs are really
frustrating.
I _barely_ miss some more guidelines on writing the docs, except for the
formal XML formats.
I _barely miss a feedback system like the "User Contributed Notes" on
php.net; even a WIKI would do well here.
My personal hall of fame for technical documentation:
1. MS SQL Server and other MS related stuff. Say what you like, but many of
the MS docs are top notch
2. Java JDK's. Tutorials, Javadocs, the Core Java books. The sheer size is
amazing.
3. php. Although I'm not a php programmer (so I don't know I was very
impressed how they put their docs together.
4. SelfHTML. A German HTML reference that is being translated to French
(finished), Spanish, English, and Japanese
(http://selfaktuell.teamone.de/extras/international.htm). _The_ standard for
years now.
5. The Netscape Javascript Guide and Reference. Although outdated, it's
still my favorite reference on that topic. I like the split up between a
guide and a reference.
6. MySQL docs. Although it sucks badly if you want to use it as a reference
and want to look for the syntax of a special SQL statement.
Hm, the only real open source initiative in this list seems to be PHP.
My conclusions:
- treat docs like source code. Use people as compiler. Use bug report
systems on docs as you would do on source code
- no release without reworked documentation.
- build a feedback loop between the writer and the reader. let them comment
on the docs, or at least let them rate them.
- have a writing-docs-101 ready to hand (I don't)
- treat docs as equally important as source code
- no excuses like "we are programmers, not writers". I like Brian's "Good
Code && Bad Documentation == Bad Code".
- Last but not least: Think about selling them. That gives the most
incentives to the writers and makes use of the quality assurance of
professional publishers (well, sometimes). That worked well for JBoss, for
example.
Regards
--Clemens
----- Original Message -----
From: "Andrew C. Oliver" <ac...@apache.org>
To: "Lucene Developers List" <lu...@jakarta.apache.org>
Sent: Sunday, July 28, 2002 9:02 PM
Subject: Re: I need your advice
> >
> >
> >(Good timing, my next article on IBM's Java Zone is a rant on the thesis
> > Good Code && Bad Documentation == Bad Code
> >)
> >
> >
> +1
>
> >--
> >To unsubscribe, e-mail:
<ma...@jakarta.apache.org>
> >For additional commands, e-mail:
<ma...@jakarta.apache.org>
> >
> >
> >
> >
>
>
>
>
> --
> To unsubscribe, e-mail:
<ma...@jakarta.apache.org>
> For additional commands, e-mail:
<ma...@jakarta.apache.org>
>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: I need your advice
Posted by "Andrew C. Oliver" <ac...@apache.org>.
>
>
>(Good timing, my next article on IBM's Java Zone is a rant on the thesis
> Good Code && Bad Documentation == Bad Code
>)
>
>
+1
>--
>To unsubscribe, e-mail: <ma...@jakarta.apache.org>
>For additional commands, e-mail: <ma...@jakarta.apache.org>
>
>
>
>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: I need your advice
Posted by Brian Goetz <br...@quiotix.com>.
> 4- If I do participate, I have to eventually get to the core of it,
> I cannot settle for supplying documentation or that sort of stuff.
(response to the community, not just to you)
If software engineering is ever to be taken seriously as an
engineering discipline (like structural engineering, for example),
we've got to ditch the collective attitude that documentation is
something peripheral, or constitutes "settling." This is the same
mistake that societally causes us to pay teachers less than
bartenders, but as an educated bunch we shouldn't be making that
same mistake.
(Good timing, my next article on IBM's Java Zone is a rant on the thesis
Good Code && Bad Documentation == Bad Code
)
To respond to Tarek, open-source communities are largely meritocratic.
You'll be able to contribute to the "core" when (a) you've
demonstrated that you contribute worthwhile stuff, and (b) you've got
something to contribute that is useful to the community. Its pretty
simple.
Welcome!
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>