I meant generalizing all manpages as short is inaccurate. The original statement was that the average is 4 pages which tells you almost nothing without some idea of the spread. You have provided that, thank you.

5831 is the number of manpages processed, or the number of total pages inside them processsed?

My system has 18,590 manpages. Running:

  cd /usr/share/man
  find ./man[0-9] -type f -exec zgrep '^[[:blank:]]*EXAMPLE' {} \;|wc -l

yields 17. While I admit that this may not be the best regular expression that would best match the pattern all the time, I think there is generally not an examples section. This may be because a lot of the documentation is for code that does not need examples.

  for i in $(seq 1 9);do echo $i $(ls man$i|wc -l);done
  1 2554
  2 454
  3 16014
  4 45
  5 346
  6 49
  7 284
  8 821

I don't have any man 9 pages, and cropped the error from that part.

While it may be true that documentation that is "easy to write, not easy to read" is a bug, I think it is very unlikely that the average person would file a bug report for documentation.

I did not know about The Linux Documentation Project's HOWTOs, very neat.

EDIT: I also wanted to point out that depending on what section you are looking at manpages for, you have different statistics.

  man1 
   Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
  1.000   1.000   2.000   5.519   4.000 470.000

  man2 
   Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
  1.000   2.000   2.000   3.018   3.000  31.000 

  man3 
   Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
  1.000   1.000   2.000   3.067   3.000 113.000 

  man4 
   Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
   1.00    1.00    2.00    3.95    5.00   21.00 

  man5 
   Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
  1.000   2.000   3.000   5.283   5.000 149.000 

  man6 
   Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
  1.000   1.000   2.000   2.306   2.000  15.000 

  man7 
   Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
  1.000   3.000   3.000   5.808   6.000  69.000 

  man8 
   Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
   1.00    1.00    2.00    3.06    3.00   77.00