On 9/24/07, Eeli Kaikkonen <[EMAIL PROTECTED]> 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 _______________________________________________ sword-devel mailing list: sword-devel@crosswire.org http://www.crosswire.org/mailman/listinfo/sword-devel Instructions to unsubscribe/change your settings at above page
