Re: Proposal - moving new docs to main tree

On Mon, 2 Oct 2006, Alexander van Loon wrote:

> On Mon, 2006-10-02 at 15:16 +0100, Alan Horkan wrote:
> > I assume this is the old documents converted to use Docbook as the master
> > format rather than Abiword files, building on the old work, not a rewrite?
> >
> > Sounds good. Maybe we could even get a step ahead of Gnome and produce
> > docbook that can be viewed in either the Gnome or KDE help browser
> > depending on what users have as their default?
>
> No, not really. The style in which the GNOME documentation is written is
> rather different, and the old documentation does not conform to my
> standards for quality. I want to produce quality documentation, I'm not
> satisfied if we simply put the old documentation in DocBook XML for
> Yelp. A lot of things aren't documented at all in the old documentation,
> the screenshots in the old documentation could also use an update, I
> could go on for a while mentioning what needs to be improved.

> Of course I still intend to copy from the old documentation if possible,
> but I'm writing different documentation for the most part. You might
> think that rewriting it is a waste of time, but I think it's worth it to
> improve documentation quality. It's a lot of work if we rewrite most of
> it of course, but I'm willing to do it.

The old documentations should continue to be shipped until the new
documentation exceeds it. Maybe I'm being too skeptical and you will be
able to salvage a lot of the old documentation so there will be very
little regression. Having seen things go badly in other projects I'd hate
to see abiword suffer similar problems of missing chunks of documentation
and things not covered in the new documentation even if they were only
badly covered by the old.

> But why would you want the documentation to be visible in KDE's help
> browser as well? KDE users already have KOffice, and as such they
> probably have very few reasons to use a GNOME/GTK app like Abiword.

Gnome and KDE are making efforts to make their docbook interoperable, if I
understand correctly there are a few extra things that need to be added to
the gnome style of docbook to help with indexing or headers. Now might
just be the time to do that.

> (currently I'm quite busy with my study and I will be away from my comp,
> so I might not answer replies to this mail until after 4 days).

Sincerely

Alan Horkan

Inkscape http://inkscape.org
Abiword http://www.abisource.com
Open Clip Art http://OpenClipArt.org

Alan's Diary http://advogato.org/person/AlanHorkan/
Received on Mon Oct 2 17:28:06 2006