Thread: Re: Interactive Documentation - how do you want it towork?
Hi Bruce, Have you ever used the idocs on the PHP site? I find them invaluable, though there are many useful comments that you might not want to incorporate into the official docs for fear of bloating them. Take a look at http://www.php.net/manual/en/function.intval.php for example. Regards, Dave. > -----Original Message----- > From: Bruce Momjian [mailto:pgman@candle.pha.pa.us] > Sent: 03 February 2003 01:09 > To: Dave Page > Cc: Neil Conway; PostgreSQL Hackers > Subject: Re: [HACKERS] Interactive Documentation - how do you > want it towork? > > > > I don't think I was clear before. When someone is looking at > the interactive docs, I would like them to say, "Oh, there's > a comment. I better read that in case it will help me." If > we have old comments, their "special" value becomes > diminished. That's why I think they should be removed as > they are reviewed. > > -------------------------------------------------------------- > ------------- > > Dave Page wrote: > > > > > > > -----Original Message----- > > > From: Neil Conway [mailto:neilc@samurai.com] > > > Sent: 02 February 2003 20:52 > > > To: Dave Page > > > Cc: PostgreSQL Hackers > > > Subject: Re: [HACKERS] Interactive Documentation - how do you > > > want it towork? > > > > > > > 2) Bearing in mind your answer to the previous question, should > > > > all > > > > the comments be deleted when useful examples have been > > > merged into the > > > > main documents (remember that the definition of 'useful' > > > may vary), or > > > > should we only remove the 'junk' ones? > > > > > > Once the comment's suggestion has been incorporated and the > > > docs updated, I think it should be removed. Just like in the > > > rest of the documentation, there's no point presenting > > > duplicate content to the user, so we should only keep the > > > idocs comments that are still relevant. The same goes for > > > comments that have no value (e.g. support requests). > > > > My concern here is that what (for example) Bruce decides is not a > > useful addition to the docs themselves, maybe something that would > > have helped me with some bizarre problem. If we dump *all* the docs > > after they have been merged then I might lose that helpful tip. > > > > Also, and perhaps more importantly, the comments will be > merged into a > > *future* version. If I am running 7.2, I'm going to look at the 7.2 > > docs, not 7.3. > > > > Regards, Dave. > > > > ---------------------------(end of > > broadcast)--------------------------- > > TIP 2: you can get off all lists at once with the unregister command > > (send "unregister YourEmailAddressHere" to > majordomo@postgresql.org) > > > > -- > Bruce Momjian | http://candle.pha.pa.us > pgman@candle.pha.pa.us | (610) 359-1001 > + If your life is a hard drive, | 13 Roberts Road > + Christ can be your backup. | Newtown Square, > Pennsylvania 19073 >
I looked at that URL, and it is good example of what _not_ to do with interactive docs, IMHO. The manual page is _very_ short, and shows no examples. The comments have various examples/cases, with corrections later to earlier postings. I would think this is not what we want. We want a longer manual page, with _correct_ examples that show typical usage. I know folks like those comments, but isn't it showing cases where the curt documentation just doesn't cut it? --------------------------------------------------------------------------- Dave Page wrote: > Hi Bruce, > > Have you ever used the idocs on the PHP site? I find them invaluable, > though there are many useful comments that you might not want to > incorporate into the official docs for fear of bloating them. Take a > look at http://www.php.net/manual/en/function.intval.php for example. > > Regards, Dave. > > > > -----Original Message----- > > From: Bruce Momjian [mailto:pgman@candle.pha.pa.us] > > Sent: 03 February 2003 01:09 > > To: Dave Page > > Cc: Neil Conway; PostgreSQL Hackers > > Subject: Re: [HACKERS] Interactive Documentation - how do you > > want it towork? > > > > > > > > I don't think I was clear before. When someone is looking at > > the interactive docs, I would like them to say, "Oh, there's > > a comment. I better read that in case it will help me." If > > we have old comments, their "special" value becomes > > diminished. That's why I think they should be removed as > > they are reviewed. > > > > -------------------------------------------------------------- > > ------------- > > > > Dave Page wrote: > > > > > > > > > > -----Original Message----- > > > > From: Neil Conway [mailto:neilc@samurai.com] > > > > Sent: 02 February 2003 20:52 > > > > To: Dave Page > > > > Cc: PostgreSQL Hackers > > > > Subject: Re: [HACKERS] Interactive Documentation - how do you > > > > want it towork? > > > > > > > > > 2) Bearing in mind your answer to the previous question, should > > > > > all > > > > > the comments be deleted when useful examples have been > > > > merged into the > > > > > main documents (remember that the definition of 'useful' > > > > may vary), or > > > > > should we only remove the 'junk' ones? > > > > > > > > Once the comment's suggestion has been incorporated and the > > > > docs updated, I think it should be removed. Just like in the > > > > rest of the documentation, there's no point presenting > > > > duplicate content to the user, so we should only keep the > > > > idocs comments that are still relevant. The same goes for > > > > comments that have no value (e.g. support requests). > > > > > > My concern here is that what (for example) Bruce decides is not a > > > useful addition to the docs themselves, maybe something that would > > > have helped me with some bizarre problem. If we dump *all* the docs > > > after they have been merged then I might lose that helpful tip. > > > > > > Also, and perhaps more importantly, the comments will be > > merged into a > > > *future* version. If I am running 7.2, I'm going to look at the 7.2 > > > docs, not 7.3. > > > > > > Regards, Dave. > > > > > > ---------------------------(end of > > > broadcast)--------------------------- > > > TIP 2: you can get off all lists at once with the unregister command > > > (send "unregister YourEmailAddressHere" to > > majordomo@postgresql.org) > > > > > > > -- > > Bruce Momjian | http://candle.pha.pa.us > > pgman@candle.pha.pa.us | (610) 359-1001 > > + If your life is a hard drive, | 13 Roberts Road > > + Christ can be your backup. | Newtown Square, > > Pennsylvania 19073 > > > -- Bruce Momjian | http://candle.pha.pa.us pgman@candle.pha.pa.us | (610) 359-1001+ If your life is a hard drive, | 13 Roberts Road + Christ can be your backup. | Newtown Square, Pennsylvania19073
Bruce Momjian wrote:> I looked at that URL, and it is good example of what _not_ to do with> interactive docs, IMHO. Themanual page is _very_ short, and shows no> examples. The comments have various examples/cases, with corrections> laterto earlier postings. I would think this is not what we want. We> want a longer manual page, with _correct_ examplesthat show typical> usage.>> I know folks like those comments, but isn't it showing cases where the> curt documentationjust doesn't cut it? Bruce is spot on here. Manuals pages that don't need an extensive amount of comments are likely the best way to go, and they're even distributed with the source code of PostgreSQL, unlike the comments. :-) Regards and best wishes, Justin Clift -- "My grandfather once told me that there are two kinds of people: those who work and those who take the credit. He told me to try to be in the first group; there was less competition there." - Indira Gandhi
On Monday, February 3, 2003, at 04:39 AM, Bruce Momjian wrote:
> I looked at that URL, and it is good example of what _not_ to do with
> interactive docs, IMHO. The manual page is _very_ short, and shows no
> examples. The comments have various examples/cases, with corrections
> later to earlier postings. I would think this is not what we want. We
> want a longer manual page, with _correct_ examples that show typical
> usage.
>
> I know folks like those comments, but isn't it showing cases where the
> curt documentation just doesn't cut it?
Well, I happen to have some erm... "experience" with the PHP system. I
can offer a bit of history in this conversation about what seems to
have worked, and what doesn't work.
What is *supposed* to happen with the pages and notes works like this:
1. Manual page goes online. Almost all manual pages begin with a bare
skeleton, derived from the raw code itself. Some developers are nice
enough to, oh, explain what it means. :-)
2. Comments, corrections, and additional examples are submitted.
3. Notes and doc editors go through all the notes, roll all of the best
ones *into* the docs, delete redundancies (2 similar examples is
silly), fix errors in the page *and* other notes, and do other garbage
cleanup.
4. Notes are removed when they are no longer relevant. A note that
duplicates current documentation would not be relevant. A note that
pertains to a version or behavior that is no longer supported is not
relevant.
5. If a page has a lot of notes, that means it should be re-documented.
There have been days when I've cleared hundreds of "notes" with ten
lines of text, and a four line code example.
After working with it (php's notes system) off and on for about 2 (3?)
years, here are some of the major *problems* in the PHP system:
1. Silly slashdot mentality, were every opinion and "tip" imaginable
gets submitted into the notes. ("If running PHP on a TRS-80 tweaked out
as a hobby project, don't forget to make sure your error logs are
written to a faster device than cassette!!.")
2. People are using the doc notes to submit bug reports. Constantly.
Annoyingly. So frequently that we automated their rejection.
3. People are using the doc notes to submit coding questions.
Constantly. Annoyingly. So frequently that we automated their rejection.
4. Keeping up with the submissions. PHP can get hundreds a day, of
which 98% or so are useless. There are people who read a "php-notes"
mailing list all day long, and at the bottom of each email is a set of
one-click URLs to take action... "reject", "edit", and "delete" (the
automation mentioned above). And yet, bad notes still get published,
because there's only so many a person can read...
5. Keeping notes editors motivated. Talk about a thankless job. :-)
6. Editing the manual page code is _much_ more complex than editing the
notes. As a result, rather than updating the manual, the notes often
get updated instead, or are never rolled into the manual. To master the
notes, you need to drive a browser. To master the docs, there's
docbook, XML, cvs, the doc structure, etc. etc. Helpful "contributors"
have an easier time with the notes.
In regards to terse vs. verbose documentation, this comes up with PHP
every so often. There are a few different angles to the issue:
1. Terse proponents who want the palm-pilot version or the windows
helpfile (CHM) of the PHP manual seem to want the tiniest amount of
text. Function prototypes and a description is about it, just as a
memory jogger.
2. Slow-link, and offline browser, users are the same way, though they
may appreciate *a single* example more.
3. The verbose proponents want user examples available in as many
formats as possible, as many tips as possible, so solving a problem
only requires *one* page.
Well, those are the challenges I've seen.
HTH with PostgreSQL.....
-Bop
That was interesting. I love the TRS-80 mention. So, it seems your
logic is pretty much the same as ours --- trim them up and improve the
docs.
So, that particular URL was an example of what _not_ to do. I have
heard folks say they like the PHP comments a lot, but I wonder how much
of that is the cutesy factor of users making comments compared to good
documentation that actually has useful, well structured information ---
it doesn't have the cutesy factor, but it does seem more useful. :-)
---------------------------------------------------------------------------
Ronald Chmara wrote:
> On Monday, February 3, 2003, at 04:39 AM, Bruce Momjian wrote:
> > I looked at that URL, and it is good example of what _not_ to do with
> > interactive docs, IMHO. The manual page is _very_ short, and shows no
> > examples. The comments have various examples/cases, with corrections
> > later to earlier postings. I would think this is not what we want. We
> > want a longer manual page, with _correct_ examples that show typical
> > usage.
> >
> > I know folks like those comments, but isn't it showing cases where the
> > curt documentation just doesn't cut it?
>
> Well, I happen to have some erm... "experience" with the PHP system. I
> can offer a bit of history in this conversation about what seems to
> have worked, and what doesn't work.
>
> What is *supposed* to happen with the pages and notes works like this:
> 1. Manual page goes online. Almost all manual pages begin with a bare
> skeleton, derived from the raw code itself. Some developers are nice
> enough to, oh, explain what it means. :-)
> 2. Comments, corrections, and additional examples are submitted.
> 3. Notes and doc editors go through all the notes, roll all of the best
> ones *into* the docs, delete redundancies (2 similar examples is
> silly), fix errors in the page *and* other notes, and do other garbage
> cleanup.
> 4. Notes are removed when they are no longer relevant. A note that
> duplicates current documentation would not be relevant. A note that
> pertains to a version or behavior that is no longer supported is not
> relevant.
> 5. If a page has a lot of notes, that means it should be re-documented.
> There have been days when I've cleared hundreds of "notes" with ten
> lines of text, and a four line code example.
>
> After working with it (php's notes system) off and on for about 2 (3?)
> years, here are some of the major *problems* in the PHP system:
> 1. Silly slashdot mentality, were every opinion and "tip" imaginable
> gets submitted into the notes. ("If running PHP on a TRS-80 tweaked out
> as a hobby project, don't forget to make sure your error logs are
> written to a faster device than cassette!!.")
> 2. People are using the doc notes to submit bug reports. Constantly.
> Annoyingly. So frequently that we automated their rejection.
> 3. People are using the doc notes to submit coding questions.
> Constantly. Annoyingly. So frequently that we automated their rejection.
> 4. Keeping up with the submissions. PHP can get hundreds a day, of
> which 98% or so are useless. There are people who read a "php-notes"
> mailing list all day long, and at the bottom of each email is a set of
> one-click URLs to take action... "reject", "edit", and "delete" (the
> automation mentioned above). And yet, bad notes still get published,
> because there's only so many a person can read...
> 5. Keeping notes editors motivated. Talk about a thankless job. :-)
> 6. Editing the manual page code is _much_ more complex than editing the
> notes. As a result, rather than updating the manual, the notes often
> get updated instead, or are never rolled into the manual. To master the
> notes, you need to drive a browser. To master the docs, there's
> docbook, XML, cvs, the doc structure, etc. etc. Helpful "contributors"
> have an easier time with the notes.
>
> In regards to terse vs. verbose documentation, this comes up with PHP
> every so often. There are a few different angles to the issue:
> 1. Terse proponents who want the palm-pilot version or the windows
> helpfile (CHM) of the PHP manual seem to want the tiniest amount of
> text. Function prototypes and a description is about it, just as a
> memory jogger.
> 2. Slow-link, and offline browser, users are the same way, though they
> may appreciate *a single* example more.
> 3. The verbose proponents want user examples available in as many
> formats as possible, as many tips as possible, so solving a problem
> only requires *one* page.
>
> Well, those are the challenges I've seen.
>
> HTH with PostgreSQL.....
>
> -Bop
>
>
-- Bruce Momjian | http://candle.pha.pa.us pgman@candle.pha.pa.us | (610)
359-1001+ If your life is a hard drive, | 13 Roberts Road + Christ can be your backup. | Newtown Square,
Pennsylvania19073
When I first saw this thread I thought of the PHP docs which I recently started
using, from a level of knowing absolutely nothing of PHP.
Sure there was some useful stuff in some of the comments but some of the pages
were very long, far more comment than manual page. A lot of the comments refer
to far earlier versions, if the reader is lucky the version addressed by a
comment is included in the comment. Also, even as a complete newbie I was able
to find errors in the comments. The upshot is that the PHP docs have a lot of
old information in them, it's guess work as to what version of PHP the comment
refers to and there are a lot of comments to read to find out this uncertain
mixture of applicable/not applicable error prone comments.[*]
On the whole, I tended stop reading the comments and looked just at the manual
page and experiment myself instead.
[*] Error prone to a large extent in the examples/techniques listed as how to
do things, the email address regexp example shown as the way that started a
whole string of followups springs to mind. However, I also found some
useful/interesting information/techniques I hadn't thought of before amongst
the stuff.
--
Nigel Andrews
On Tue, 4 Feb 2003, Bruce Momjian wrote:
>
> That was interesting. I love the TRS-80 mention. So, it seems your
> logic is pretty much the same as ours --- trim them up and improve the
> docs.
>
> So, that particular URL was an example of what _not_ to do. I have
> heard folks say they like the PHP comments a lot, but I wonder how much
> of that is the cutesy factor of users making comments compared to good
> documentation that actually has useful, well structured information ---
> it doesn't have the cutesy factor, but it does seem more useful. :-)
>
> ---------------------------------------------------------------------------
>
> Ronald Chmara wrote:
> > On Monday, February 3, 2003, at 04:39 AM, Bruce Momjian wrote:
> > > I looked at that URL, and it is good example of what _not_ to do with
> > > interactive docs, IMHO. The manual page is _very_ short, and shows no
> > > examples. The comments have various examples/cases, with corrections
> > > later to earlier postings. I would think this is not what we want. We
> > > want a longer manual page, with _correct_ examples that show typical
> > > usage.
> > >
> > > I know folks like those comments, but isn't it showing cases where the
> > > curt documentation just doesn't cut it?
> >
> > Well, I happen to have some erm... "experience" with the PHP system. I
> > can offer a bit of history in this conversation about what seems to
> > have worked, and what doesn't work.
> >
> > What is *supposed* to happen with the pages and notes works like this:
> > 1. Manual page goes online. Almost all manual pages begin with a bare
> > skeleton, derived from the raw code itself. Some developers are nice
> > enough to, oh, explain what it means. :-)
> > 2. Comments, corrections, and additional examples are submitted.
> > 3. Notes and doc editors go through all the notes, roll all of the best
> > ones *into* the docs, delete redundancies (2 similar examples is
> > silly), fix errors in the page *and* other notes, and do other garbage
> > cleanup.
> > 4. Notes are removed when they are no longer relevant. A note that
> > duplicates current documentation would not be relevant. A note that
> > pertains to a version or behavior that is no longer supported is not
> > relevant.
> > 5. If a page has a lot of notes, that means it should be re-documented.
> > There have been days when I've cleared hundreds of "notes" with ten
> > lines of text, and a four line code example.
> >
> > After working with it (php's notes system) off and on for about 2 (3?)
> > years, here are some of the major *problems* in the PHP system:
> > 1. Silly slashdot mentality, were every opinion and "tip" imaginable
> > gets submitted into the notes. ("If running PHP on a TRS-80 tweaked out
> > as a hobby project, don't forget to make sure your error logs are
> > written to a faster device than cassette!!.")
> > 2. People are using the doc notes to submit bug reports. Constantly.
> > Annoyingly. So frequently that we automated their rejection.
> > 3. People are using the doc notes to submit coding questions.
> > Constantly. Annoyingly. So frequently that we automated their rejection.
> > 4. Keeping up with the submissions. PHP can get hundreds a day, of
> > which 98% or so are useless. There are people who read a "php-notes"
> > mailing list all day long, and at the bottom of each email is a set of
> > one-click URLs to take action... "reject", "edit", and "delete" (the
> > automation mentioned above). And yet, bad notes still get published,
> > because there's only so many a person can read...
> > 5. Keeping notes editors motivated. Talk about a thankless job. :-)
> > 6. Editing the manual page code is _much_ more complex than editing the
> > notes. As a result, rather than updating the manual, the notes often
> > get updated instead, or are never rolled into the manual. To master the
> > notes, you need to drive a browser. To master the docs, there's
> > docbook, XML, cvs, the doc structure, etc. etc. Helpful "contributors"
> > have an easier time with the notes.
> >
> > In regards to terse vs. verbose documentation, this comes up with PHP
> > every so often. There are a few different angles to the issue:
> > 1. Terse proponents who want the palm-pilot version or the windows
> > helpfile (CHM) of the PHP manual seem to want the tiniest amount of
> > text. Function prototypes and a description is about it, just as a
> > memory jogger.
> > 2. Slow-link, and offline browser, users are the same way, though they
> > may appreciate *a single* example more.
> > 3. The verbose proponents want user examples available in as many
> > formats as possible, as many tips as possible, so solving a problem
> > only requires *one* page.
> >
> > Well, those are the challenges I've seen.
> >
> > HTH with PostgreSQL.....
> >
> > -Bop
> >