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