Re: [privoxy-devel] [P] The next Privoxy release

[Fabian K. <fre...@fa...>]

Hal Burgiss <ha...@bu...> wrote:

> On Tue, Oct 30, 2007 at 09:33:25PM +0100, Fabian Keil wrote:
>=20
> > > Just for the docs, some things that are last minute things to do (and
> > > maybe we can change some of this to make life easier):
> >=20
> > Do you mean change it eventually, or before the next release?
>=20
> These are the kinds of things that get done before each release. The
> biggest concern is regenerating config, and making sure all these
> things are up to date, and synced with code,project goals, etc. There
> is a lot of verbiage there.

I too think the there are too many comments in the configuration
file, but I don't think it's an important problem we have to
fix before the next release.

doc/source/p-config.sgml should be up-to-date when it comes
to listing available options, we just have to disable the
options mentioned before and provide a reason.

> > Currently you and Roland seem to be the only people who can
> > reliable build the documentation and I think if everyone could
> > do it, there would be a lot more documentation already.
>=20
> Is more documentation what we need or less? Its a rare day a change
> gets made to the Developer's manual. The user manual I think is very
> good, but it is so large now, its difficult to maintain. And does
> anyone read all of it? Most of it? Some of it?

I think our current documentation in general is somewhat brief.

Experienced users will most of the time get the information they
need, while new users with limited technical knowledge probably
don't.

The main reason the Developer's manual doesn't get
updated is probably lack of time, not because there's
nothing to update or add. At least for me the user
manual has the higher priority so I usually edit that.

I don't know how many users read our documentation either.

=46rom the problem reports one gets the impression that
most don't read anything, but that may also be because
users who solved their problems with the help of the
documentation usually don't file problem reports.

> > My preference for the next two releases would be to build the documenta=
tion
> > any way you seem fit, and to garbage-collect the current documentation =
build
> > system later on to replace it with something better.
>=20
> Any way we go it is some _work_. Right now the easiest thing is
> probably to do it like we have.

Ok.

> > The ChangeLog currently contains some entries with information
> > that could be added to both of these sections and unlike these
> > sections it's also only a bunch of commits behind the actual code.
>=20
> ;-). I think it is important to highlight changes and new features.

And I agree. It's just that from my memory the "What's New"
section and the "Upgrader's Notes" haven't been updated
for quite some time now. The ChangeLog has and some of
the content could be copy&pasted with minor modifications.
 =20
> > Is there some kind of deadline by which the rest of us should have
> > our act together? Presumably you'd prefer to build the documentation
> > once ...
>=20
> Not really.=20
>=20
> Once all the pieces are in place, the build process is easy and can be
> done multiple times very easily.=20

Fancy that.

I thought one always had to verify that it didn't silently fail.
=20
> The one thing that I'd really want to do one time is the config
> generation. Just because it has to be manually tuned, and it is easy
> for an error to creep in (like unwanted line breaks). I think we
> released with a messed up config one time for just that reason. A
> typo or mistake in document is one thing, but in a config file ...

Makes sense.

Fabian