Re: updating the documentation, and displaying the docs in yelp - bug #8732

On Thu, 3 Aug 2006, Sander van Loon wrote:

> Date: Thu, 03 Aug 2006 20:21:37 +0200
> From: Sander van Loon <svloon@xs4all.nl>
> To: "abiword-dev@abisource.com" <abiword-dev@abisource.com>
> Subject: updating the documentation,
> and displaying the docs in yelp - bug #8732
>
>
> http://bugzilla.abisource.com/show_bug.cgi?id=8732
>
> This bug is more than a year old now.

I am sure there are many older bugs but age of a bug doesn't mean much.

> Besides that the documentation is not displayed in GNOME's Yelp, but in
> a HTML page with a horrible layout using a web browser,

I am not a huge fan of the layout but if you are familiar with Cascading
Style sheets you could come up with an alternative since the look of the
help files was carefully kept seperate from the information.

> it was also noted that the current documentation is out of date.

The help you have offered in updating the documentation will be much
appreciated.

> I hope the developers will soon fix the first issue, integration with
> GNOME is important for Abiword if you ask me.

Do you have any examples of other applications using the Gecko based Yelp
to view HTML documentation?

Another more developer intensive approach might be to try and use Abiword
to Generate docbook files and get Yelp to use those but I do not know if
the Docbook exporter is suitable for that yet.

> I'm prepared to fix the
> second issue, I'm willing to rewrite the documentation.

You mean update right? Rewriting from scratch would be a waste of your
time and all the work which has previously gone into the
documentation.

> I'm still enjoying my vacation so I should have a lot of time to work on
> it at the moment, when I start my education again in September I should
> still have time to work on it, but not as much.
>
> While English is not my native language, I think my skills in it are
> sufficient. I have talent for writing, so I'm probably the right man for
> the job.

If you sumbit patches and ask people to proof read them first it
shouldn't be too much of a problem, your written English seems more
than good enough and hopefully as a non-native speaker you will want
to keep it simple and clear and avoid techincal jargon which can only be a
bonus.

> The question is, where do I start? I should probably get in contact with
> the GNOME documentation team to figure out how to write documentation
> usable for Yelp,

There are standard methods, essentially you would take their template and
create documentation for abiword using that. However since abiword
already has documentation I would not recommend you try to create a whole
new set of documentation since there are probably better ways to convert
or integrate what we already have.

> KOffice for examples. But are the developers willing to implement Yelp
> support in the near future, so that my contribution will become useful?
> And others who can help me? I assume it's a huge job to write
> documentation for a word processor.

There is a lot you could do to help out and make sure there is
documentation explaining newer features, but rewriting a whole new set of
documentation does not seem like the best approach. Improving what we
already have and finding ways to integrate it into Yelp seems like the way
to go.

--
Alan