If you stay with a wiki for the documentation, it makes sense to stick with the one at GitHub, assuming it provides the needed functionality. I'm most familiar with MediaWiki, since that's what underpins wikipedia. MediaWiki could also provide the needed functionality.
I think, though, that having the documentation in some text-based format like latex or docbook would be nice. Both of those formats allow for linking. With pdflatex I know you can create a document with good links between the parts of the document. I'm not very familiar with latex->html converters, but I know that some exist. The upside of latex is that most if not all of the researchers actively using moses should be familiar with latex. I am not as familiar with docbook. Docbook has the advantage of good converters to both pdf and html. I believe it can transparently handle linking. With either latex or docbook, we could easily include the appropriate scripts to allow authors to compile their changes into pdf and html for previewing. Appropriate commit hooks could then post those exported pdf documents and html pages to the web site after each commit to the github repo. I think that a wiki potentially provides the lowest bar to entry, but that latex or docbook is overall the best solution. Having the docs in a git repo is also a fairly low bar to entry. Lane On Tue, Apr 10, 2012 at 1:05 PM, Christian Federmann <[email protected]>wrote: > Hi all, > > wouldn't it make more sense to make use of the Wiki infrastructure GitHub > offers, then? > > I doubt setting up a Trac (even with Git integration) would give any > benefits over GitHub; just my 2 cents, though... > > Cheers, > Christian > > > > -- > Dipl.-Inf. Christian Federmann, Researcher, Language Technology Lab > Office +1.09 -- Phone +49-681/857-75-5353, Fax +49-681/857-75-5338 > DFKI GmbH, Campus D3 2, Stuhlsatzenhausweg 3, 66123 Saarbruecken > http://www.dfki.de/~cfedermann > > ------------------------------------------------------------------- > Deutsches Forschungszentrum fuer Kuenstliche Intelligenz GmbH > Trippstadter Strasse 122, D-67663 Kaiserslautern, Germany > Geschaeftsfuehrung: > Prof. Dr. Dr. h.c. mult. Wolfgang Wahlster (Vorsitzender) > Dr. Walter Olthoff > Vorsitzender des Aufsichtsrats: > Prof. Dr. h.c. Hans A. Aukes > Amtsgericht Kaiserslautern, HRB 2313 > ------------------------------------------------------------------- > Sent with Sparrow (http://www.sparrowmailapp.com/?sig) > > > On Tuesday, 10. April 2012 at 19:00, Joerg Tiedemann wrote: > > > Maybe a tool like Trac (http://trac.edgewall.org/) would be the best > > alternative. > > Trac comes with a wiki and has a lot of other useful tools like a > > ticket system, roadmaps, etc. > > It can link to the source code and highlight it. It is simple to use, > > includes user/permission management and has lots of useful extensions. > > But I'm not sure how easy it is to convert the existing documentation. > > > > Jörg > > > > > > On Tue, Apr 10, 2012 at 6:23 PM, Hieu Hoang > > <[email protected](mailto: > [email protected])> wrote: > > > i think it's only easy to do the easy things in the present wiki. > > > > > > It's impossible to add a picture, or an equation, or to add a new > > > section to the sidebar, without ssh access to the edinburgh server. And > > > err root access... > > > > > > and it's impossible to add user-based access or to be notified when the > > > wiki's being changed. This kinda of means we can never let newer people > > > edit the wiki, which is a shame since the docs are mostly for them and > > > they should have the ability to edit it too. Ideally, i think it should > > > be a cross between a manual and a stackoverflow forum. > > > > > > mediawiki might be another idea > > > > > > > > > > > > On 10/04/2012 22:07, Barry Haddow wrote: > > > > 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]) > > > > > > <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] (mailto:[email protected]) > > > > > > http://mailman.mit.edu/mailman/listinfo/moses-support > > > > > > > > > > > > > > > > > > > > > -- > > > > Barry Haddow > > > > University of Edinburgh > > > > +44 (0) 131 651 3173 > > > > > > > > > _______________________________________________ > > > Moses-support mailing list > > > [email protected] (mailto:[email protected]) > > > http://mailman.mit.edu/mailman/listinfo/moses-support > > > > > > > > > > > > -- > > > ********************************************************************************** > > Jörg Tiedemann [email protected] (mailto: > [email protected]) > > Dep. of Linguistics and Philology http://stp.lingfil.uu.se/~joerg/ > > Uppsala University tel: +46 (0)18 - 471 1412 > > Box 635, SE-751 26 Uppsala/SWEDEN fax: +46 (0)18 - 471 1094 > > > > _______________________________________________ > > 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 > -- When a place gets crowded enough to require ID's, social collapse is not far away. It is time to go elsewhere. The best thing about space travel is that it made it possible to go elsewhere. -- R.A. Heinlein, "Time Enough For Love"
_______________________________________________ Moses-support mailing list [email protected] http://mailman.mit.edu/mailman/listinfo/moses-support
