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

[Jonathan Morgan]

On 9/24/07, Eeli Kaikkonen <eekaikko at mail.student.oulu.fi> wrote:
> 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.

That makes sense, though I don't think that will overcome the "I want
to use language X, for some value of X unserved by SwigSword".

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

I use PyQt for work, so I understand entirely what you say about the
Qt documentation.  I think it is very good.

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

That was a reaction to DM's statement:
"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 don't think that the Wiki is appropriate for the API documentation I
was talking about, so the Wiki was the "one source" I was targeting.

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

Which is why I said it.

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

The fact that it's out of scope doesn't change the fact that it may
end up being included in a conversation about "documentation", which,
as I pointed out, has fairly wide ranging meanings.  This was again in
response to DM's comments on understanding GUIs (which may, for all I
know, have been talking about developer documentation of GUIs).

Jon