On 9/24/07, DM Smith <[EMAIL PROTECTED]> 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 _______________________________________________ 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
