Hi Folks Thanks for all your suggestions!
I'm not convinced about putting the documentation into github. At the moment the documentation is in a wiki, which is good because it's really easy to edit, the results of an edit are immediate, and you end up with a linked set of html documents. The main issue that I see is that there is only one password, so there's no way for people to get credit for their edits or create areas to upload their own stuff. If we move to github, with the primary documentation written in Latex, then it seems to make it harder to contribute. Not everyone knows Latex, it's harder to link across documents with Latex, and you have to wait at least until you check it in before you see how it affects the website. Wikis should make collaborative editing easier, in a way that a document checked into source control doesn't. Also, if we go down the github/latex (or github/docbook or whatever) route, then there's a bit of hacking to convert the existing documentation to editable latex, and rig up commit hooks in github. (I know we generate latex from the existing documentation, but the generated latex is probably not suitable for human editing). I suppose if we think github/latex is a good route then these problems could be overcome. Another option would be to switch to a different wiki option (e.g. mediawiki) which allows user accounts and comments on pages. That would mean that people could add their own pages, getting credit for their edits. It also has pdf book export built-in. There would still be the format conversion pain... cheers - Barry On Tuesday 10 April 2012 14:42:11 Hieu Hoang wrote: > I think putting it as a special branch of github is a good idea. > Anything where other people can add there own stuff to the docs is cool. > > another thing we might want is to be able to let people comment on a > particular section. eg. suggested changes/queries. It might also move > some of the newbie questions away from the mailing list > > there's just the small matter of cutting & pasting everything from the > current docs... > > On 10/04/2012 20:01, Lane Schwartz wrote: > > Barry, > > > > What about making a special branch in the git repo for documentation? > > > > That way anyone with access to the git repo could easily add to the > > documentation as needed. > > > > The nightly build could just check out that branch and compile it from > > whatever format you want people to edit it in (presumably latex or > > possibly docbook) into pdf (and possibly also html). > > > > Cheers, > > Lane > > > > > > On Tue, Apr 10, 2012 at 8:51 AM, Barry Haddow <[email protected] > > <mailto:[email protected]>> wrote: > > > > Hi Folks > > > > I'm going to be spending some time over the next couple of weeks > > improving the > > Moses documentation (http://www.statmt.org/moses/), with the aim > > of making the > > Moses manual more up-to-date and useful. > > > > I'd therefore like to know if anyone has any comments or > > corrections for the > > existing documentation, or suggestions on how to improve it. If > > you do, then > > please either mail me directly, or mail this list if you think > > it's more > > approriate. > > > > I'd also be interested to hear your suggestions as to how to > > enable more > > people to contribute to the documentation. The Moses documentation is > > currently hosted on PmWiki, with password-enabled editing, and the > > manual is > > produced nightly by converting the wiki to latex and compiling it > > to pdf. > > However there might be other systems which would make it easier > > for anyone to > > sign up and contribute, > > > > thanks for your help! > > > > cheers - Barry > > > > -- > > The University of Edinburgh is a charitable body, registered in > > Scotland, with registration number SC005336. > > > > _______________________________________________ > > Moses-support mailing list > > [email protected] <mailto:[email protected]> > > http://mailman.mit.edu/mailman/listinfo/moses-support > > > > > > > > > > > > > > _______________________________________________ > > Moses-support mailing list > > [email protected] > > http://mailman.mit.edu/mailman/listinfo/moses-support > -- Barry Haddow University of Edinburgh +44 (0) 131 651 3173 -- The University of Edinburgh is a charitable body, registered in Scotland, with registration number SC005336. _______________________________________________ Moses-support mailing list [email protected] http://mailman.mit.edu/mailman/listinfo/moses-support
