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

[Jonathan Morgan]

On 9/24/07, DM Smith <dmsmith555 at yahoo.com> wrote:
> My 2 cents on the state of documentation:
>
> I find that documentation is the first thing that developers want
> access to and the last thing they want to write. It seems that there
> is always one more important thing to fix or add. And once a
> developer has an understanding how to use the code, having good
> documentation is relatively unimportant. Currently, we have
> significant implementations for each major platform (Win, Mac, Linux
> and Web) and it is understanding these GUIs that becomes more important.
>
> Having excellent documentation for the Sword API would minimize,
> perhaps circumvent, the common question that we are asked: "I want to
> write my own Bible application, using my favorite computer language.
> 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?

> Open source is a community process. It should be that anyone can
> freely participate in the process. With regard to documentation, we
> all have the ability to provide it and make it available via the
> wiki. That's what the wiki's home page states it is for.

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.

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).

It is true that software developers tend not to like writing
documentation of any sort.  I would agree that some work needs to be
done on these things.  However, because I see them as separate things
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.

I would suggest the following:

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.

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.

3. UI documentation: This would be largely the responsibility of
individual front ends.  The different platforms have different
conventions for how user help works and what it should include, so
there is no point suggesting anything in particular, but it really
should be there in some form.

In addition there are other things that people may want from documentation:
1. Tutorials, possibly for all of developers (how to use the sword
API), module makers (how to use the sword tools), and users (how to
use a particular UI).  Those for (1) and (2) belong either with the
Sword distribution or on the Wiki.  Those for (3) belong with the user
documentation.
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.

I may be able to help in some of these areas in a few months, but at
the moment I can only suggest.  There is a chance that I have got
these things completely wrong - if so, correct me.  There are many
things that are wanted, but I think we all need to remember that this
is a volunteer effort, not a commercial enterprise.

Jon