Proofreading man-pages?

[Jukka Ruohonen-3]

Hello.

As I recently got my printer working again with lpd(8), I was thinking about
starting a hobby-project with NetBSD man-pages. Basically: print them all
out and start reading with a pencil.

While my english may not be fluent, I think this method would catch a big
amount of typos, incorrect cross-references, stylistic flaws and other
miscellaneous bugs.

Has someone carried out such an undertaking? How many A4 pages are we
talking about? Any recommendations?

- Jukka,

[Jeremy C. Reed]

On Fri, 15 May 2009, Jukka Ruohonen wrote:

> As I recently got my printer working again with lpd(8), I was thinking about
> starting a hobby-project with NetBSD man-pages. Basically: print them all
> out and start reading with a pencil.
>
> While my english may not be fluent, I think this method would catch a big
> amount of typos, incorrect cross-references, stylistic flaws and other
> miscellaneous bugs.
>
> Has someone carried out such an undertaking? How many A4 pages are we
> talking about? Any recommendations?

Yes, I have been working on it. But only section 8 and a few section 1 for
now.

It is well more than 6500 printed pages. (I am only doing section 8 for
now and will cost me a few hundred dollars to get books printed and I
will offer for around US$33 for man 8 set of two or three books. Once I
have completed cover I will submit.)

(I also emailed you off list with more details.)

[Hubert Feyrer-4]

On Fri, 15 May 2009, Jukka Ruohonen wrote:
> Has someone carried out such an undertaking? How many A4 pages are we
> talking about? Any recommendations?

IIRC it was like 2000 last time I checked.
Good luck! ;-)

(FWIW: We'll be happy to take back patches in electronic form, against
*roff sources :)


  - Hubert

[Jukka Ruohonen-3]

On 15.05.2009, Jeremy C. Reed wrote:
>
> Yes, I have been working on it. But only section 8 and a few section 1 for
> now.
>
> It is well more than 6500 printed pages. (I am only doing section 8 for
> now and will cost me a few hundred dollars to get books printed and I
> will offer for around US$33 for man 8 set of two or three books. Once I
> have completed cover I will submit.)

Frankly, I had no idea that this would account to that many printed pages.
In this case going section-per-section is probably indeed the best solution,
ergonomically and otherwise.

As for Hubert's comment, well yes, luck and a lot of patience is needed :-).
Yet, call me old-fashioned but reading from paper is actually the only way
to proofread. (For comparable reasons I think these so-called e-books will
never succeed.)

- Jukka.

[David H. Gutteridge]

On Fri, 15 May 2009 14:02:45 +0300, Jukka Ruohonen wrote:
 >Hello.
 >
 >As I recently got my printer working again with lpd(8), I was  
thinking about
 >starting a hobby-project with NetBSD man-pages. Basically: print  
them all
 >out and start reading with a pencil.
 >
 >While my english may not be fluent, I think this method would catch  
a big
 >amount of typos, incorrect cross-references, stylistic flaws and other
 >miscellaneous bugs.
 >
 >Has someone carried out such an undertaking? How many A4 pages are we
 >talking about? Any recommendations?
 >
 >- Jukka,

If you're getting into this sort of endeavour, you might want to have a
look at the 181 open doc-bug PRs so you're not duplicating any efforts.
There are some interesting things in there, like this:
http://www.netbsd.org/cgi-bin/query-pr-single.pl?number=9627

(I'm sure there are some old documentation PRs that are no longer
relevant and can be closed, for that matter.  There are duplicates
complaining about IPF documentation being out of date or incomplete,
for instance.)

Regards,

Dave