[sword-devel] OT: project issues (was: Re: single-user vs. multi-user installations, modules and packaging)

[Eeli Kaikkonen]

On Mon, 24 Sep 2007, Jonathan Morgan wrote:
> > How do I export the content of the modules so I can store it in my
> > own format?"
>
> Might this not need better documentation of the Sword project tools,
> rather than the API?

I think he meant that people would be more willing to write software
using our library. That would remove the need of conversion.

> I think that there are a few separate issues here:
> 1. Documentation of the API.  This should consist of documentation of
> what the classes are for, what the individual methods do, etc.
> 2. Documentation of the Sword tools.  This should consist of
> documentation of input file formats, purpose, command line arguments,
> etc.
> 3. Documentation for the various GUIs.  This should consist largely of
> user manuals and similar things.

Exactly, but the library is for developers and frontends for end users.
Therefore their documentation projects are not related.

> I think that in all these areas there is some work done.  I think what
> Eeli and Karl were looking at was (1), while DM may be looking more at
> (2) and (3) (correct me if I'm wrong).

I was actually thinking of 1 and 2 though it might not be clear from
what I wrote.

I don't expect anyone here to become interested in one GUI library
called Qt, but please look at http://doc.trolltech.com/4.3/index.html.
Can you imagine more informative front page for a library documentation?
There are sections for tutorials, technologies, developer tools, API
etc. All you can hope for in one place. Everything is written
consistently in the same HTML format. If we had similar page it would
include links to the library API, different tools, tutorials etc.

> with different audiences, I think that there is a real danger of
> trying to lump them together and either ending up with one source for
> documentation which doesn't really meet any needs, or with some needs
> not being met at all.  For example, (1) would be definitely targeted
> at developers, (2) is probably directed at module developers (though
> they should have some knowledge of command line tools, etc.), and (3)
> should be directed at end users.

Number 3 is out of our scope as I mentioned. I don't see any reason why
things should be "lumped together". Having a centralized page for
developer documentation is not lumping together. I don't understand what
you mean by "one source". See how Qt documentation is consistent in form
and style, yet very useful for their audiences.

> 1. API documentation: This should probably be kept with the source at
> this stage.  I am aware that there are some arguments for separating
> this from the source for documentation of major software libraries
> like Mono (such as internationalisation), but I think at the moment
> the library is struggling to have adequate documentation in one
> language.  From this documentation can be generated, and there is a
> higher chance of it being kept in sync with the code.

This is right and I don't see a reason why we should ever remove the doc
from the code files. Few widespread sofware libraries have 18n'ed docs
(or am I wrong? Haven't researched lately...). Keeping the translations
up to date would be almost impossible for us.

>
> 2. Tool documentation: Basic documentation of what individual tools do
> should probably be with the source.  More detailed user level things
> like "What tools should I use to create a module?", "How do each of
> the tools fit into the big picture?", "How do I create an OSIS
> module?", etc. probably belong on the Wiki, as has been done to a
> reasonable extent.

That's true. Using wiki is practical for these kind of things.

> 3. UI documentation: This would be largely the responsibility of
> individual front ends.

As I said I think it's complitely out of our scope. Each frontend takes
care of its documentation and they have completely different audience.

> 2. Documentation of Sword conventions, such as where to install
> modules.  This is necessary for compatibility between multiple front
> ends.  These kinds of things are often discussed on the mailing list
> and agreed on, but never stored anywhere else.  You can be fairly
> certain that when the next front end developer comes along in a year's
> time that they will not wish to read through a year's worth of
> sword-devel emails to try and discover these things.  These things may
> be best stored on the Wiki.

Right.

  Yours,
	Eeli Kaikkonen (Mr.), Oulu, Finland
	e-mail: eekaikko at mailx.studentx.oulux.fix (with no x)