How do you guys tackle a package with poorish documentation?

[Ben Finney]

"Veek. M" <vek.m1234 at gmail.com> writes:

> My question is: how do you guys deal with a situation like this? Do you 
> look through the source code? Do you switch to scapy? Do you now look 
> for books on scapy - there are quite a few, with chapters covering it.

Once you realise that there is significantly less incentive *for the
software maintainer* to spend the effort required in producing and
maintaining and distributing high-quality documentation, you necessarily
realise that someone must apply such an an incentive — otherwise the job
simply is not done.

With that realisation, it becomes immediately clear who has such an
incentive: newcomers to the library. Such as you and me.


So, when working through an unfamiliar library, make it a habit to
record the questions that are not immediately answered. Try to answer
them and record those answers in the same place.

Once you have enough understanding to know what works and what doesn't,
you will inevitably have a set of questions that were raised by trying
to learn the library, and were not answered in any obvious place.

Take those, file bug reports, make suggested patches to improve the
documentation.

All this assumes the project is community-maintained. If you come across
a library that is not community-maintained, walk away as soon as you
realise it; the hope of improvement is much lower.

> A lot of my time goes to the dogs browsing for stuff so I was
> wondering if that's the norm?

Until we make it the norm to *demand* better standards from each other,
and provide the example of doing that work with and for each other: yes.

-- 
 \        “A free press is one where it's okay to state the conclusion |
  `\                      you're led to by the evidence.” —Bill Moyers |
_o__)                                                                  |
Ben Finney