Mailing List Archive: Good Software/Documentation was Re: I need your advice

Good Software/Documentation was Re: I need your advice

Jul 28, 2002, 12:01 PM

Post #1 of 5 (360 views)

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: <mailto:lucene-dev-unsubscribe@jakarta.apache.org>
>For additional commands, e-mail: <mailto:lucene-dev-help@jakarta.apache.org>

--
To unsubscribe, e-mail: <mailto:lucene-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:lucene-dev-help@jakarta.apache.org>

Re: Good Software/Documentation was Re: I need your advice [ In reply to ]

brian at quiotix

Jul 28, 2002, 12:17 PM

Post #2 of 5 (358 views)

Permalink

> 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: <mailto:lucene-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:lucene-dev-help@jakarta.apache.org>

Re: Good Software/Documentation was Re: I need your advice [ In reply to ]

acoliver at apache

Jul 28, 2002, 12:22 PM

Post #3 of 5 (351 views)

Permalink

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: <mailto:lucene-dev-unsubscribe@jakarta.apache.org>
>For additional commands, e-mail: <mailto:lucene-dev-help@jakarta.apache.org>
>
>
>
>

--
To unsubscribe, e-mail: <mailto:lucene-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:lucene-dev-help@jakarta.apache.org>

Re: Good Software/Documentation was Re: I need your advice [ In reply to ]

brian at quiotix

Jul 28, 2002, 12:28 PM

Post #4 of 5 (346 views)

Permalink

> 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: <mailto:lucene-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:lucene-dev-help@jakarta.apache.org>

Re: Good Software/Documentation was Re: I need your advice [ In reply to ]

cmad at lanlab

Jul 29, 2002, 2:57 AM

Post #5 of 5 (344 views)

Permalink

> <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: <mailto:lucene-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:lucene-dev-help@jakarta.apache.org>