[Worldforge-all-lists] Re: [WF-Server] STAGE design docs

[Bryce H. <br...@ne...>]

On Fri, 9 Feb 2001, Garrett Banuk wrote:
> The format of the texts would probably best be done in html, this is
> how the SDL document project does it and this seems to be the most
> successful way. Everyone can read html and it is very simple to write too,
> as a matter of fact most people can already write html. Html will also
> support linking to other pages, objects for examples, and inserting
> images. You could have a nice neat list of an API for something, then each
> API can be clicked on and it's information will be pulled up. With LaTeX
> and other typesetting formats, you just have to put everything on one page
> and make it harder to read.

I would like you to try out LaTeX a bit more.  I prefer that format.
Please try out the tex -> pdf and html converters.

> As for creating the repository, I think some scripting would be needed
> here so people could submit changes through a webpage. Or maybe just do a
> CVS of an entire tree of the html files. People can take out text files,
> make changes and resubmit them. I think CVS would be good as this will
> support a high amount of changes from different users easily, just like
> editing .c/.cpp source.

Having tried it several different ways, I think you're right that the
CVS interface is a very good way to access the files.  I agree that it
would be nice to have a script that allows web access, sorta like wiki,
but CVS access is sufficient.

> To have a team of people specifically devoted to documentation might get
> messy as these people will have to go through the entire project, collect
> things and display them all. Then they will have to stay updated on all
> the changes either by reading changelogs from other people or having
> changes sent to them. This will probably lead to burnout in the doc team
> quickly if there are a lot of changes. Also if the doc team doesn't
> understand how something works and where it is ordered, this could cause
> erroneous documentation to be created.

These are all concerns I myself have had over the years, myself.  But I
think they are not impossible obstacles, if we put our dedication into
it.  It will be tough to find good people to make the docs, and they
will have some difficulty overcoming the messiness, but in the end it
will well be worth it.  Just consider how much admiration that
well-documented open source projects get, and I think you will have to
agree. 
 
> I think the reason why this works with the SDL doc team is that the rate
> of new changes is quite low, like only a few minor changes per week (bug
> updates), and then a large update when a new version of the library comes
> out. With something like WorldForge, there will probably be a lot of
> updates daily.

*Grin*  This has occurred to me as well, although I think you've phrased
it better than I could.  It's hard to justify putting time into writing
docs when there is a chance that there still might be changes ahead. 

> Wow, I've been writing a lot tonight, maybe I should be doing the
> documentation. =)

Ahem.  ;-)

Bryce


_______________________________________________
Server mailing list
Se...@ma...
http://mail.worldforge.org/lists/listinfo/server