Brad, This is all well and good, and I think this sounds like a good route to go. I'd support either a Wiki-route or Docbook (I don't know Docbook, but would be willing to learn if necessary).
However, I think what we are missing right now (which Claudia and Mark W. have pointed out) is an interim solution. At this point, confusion as to where to submit new documentation (wiki, [EMAIL PROTECTED] or HTML) is causing everyone headaches. Not only does it confuse those of us that want to help build better documentation, but it is also obviously making it more difficult for you to merge changes from various different sources. What I'd suggest is coming up with a single, interim point of change. So, if (for the interim) we say that the HTML docs are still official, then everyone will know to make official updates there. The current situation is a tad confusing since even many of the Committers don't know where to make documentation updates, such that the updates don't end up "lost" in the various merges... - Tim Bradley McLean wrote: > Hello all- > > The foundation is trying to find a way to meet the long term goals of > having the documentation in a readily editable form, and still product > a manual periodically. > > For the short term, we (I) am walking through the submitted doc > changes to webmaster, and working from the existing .doc file for > 1.5.0. I consider myself informed that I'll need to do my best to > diff the [dspace-source]/docs html as well. > > I'm hoping we'll be able to roundtrip wiki <-> doc (really .pdf) in > chapter sized pieces. We haven't been considering a docbook > conversion. I'd give that some consideration if we felt there was a > large enough pool of contributors that would work in that form, and if > we could work out how to edit the initial conversion into usable form. > > So the answer to "what are the foundation's documentation processes" > is that it's evolving. We have the existing doc file and the existing > html to work from, and we want to have a low friction mechanism for > the community to provide edits. We also want to be able to package a > single document manual to accompany future releases. Your input on > this is welcome. > > -Brad > > On Jul 24, 2008, at 2:39 AM, Claudia Jürgen wrote: > >> Hi Mark, >> >> the divergence is one problem. There have been updates to the >> [dspace-source]/docs after the manual release and not everything which >> was in the docs (e.g. submisssion documentation) went into the manual. >> >> Furthermore we need a way to join in the documentation efforts of the >> Foundation. Mailing discrepancies to [EMAIL PROTECTED] as indicated >> in the docs page isn't really a collaborative tool. And how should >> current changes be handled? The [dspace-source]/docs and the manual >> are >> quite different atm as changes done during the manual creation were >> not >> reflected in the source docs. >> >> As for the manual itself. I had a quick run through it and it seems to >> be part [dspace-source]/docs and part wiki and other sources like >> howtos. Some big chunks e.g. the submission configuration are missing >> and there are loads of references to the pre-maven state. Naturally I >> mailed everything I found to dspace.org but that was the moment I >> started worrying about the documentation process in general. >> >> sunny greetings >> >> Claudia >> >> >> Mark Diggory schrieb: >>> I'm limiting this to the tech list to stop the cross posting. >>> >>> This divergence "is" the problem. We need to take advantage of the >>> resources the Foundation have provided here ASAP. If there are >>> discrepancies, they need to be sent into Brad, Valerie, MIchele etc >>> to assure they get into the documentation there. My understanding is >>> that the documentation really hasn't changed since the 1.5.0 release >>> and if there are differences I'd be surprised because I understood >>> what the Foundation to be working on was a copy of that original >>> documentation. >>> >>> -Mark >>> >>> On Jul 21, 2008, at 11:15 PM, Claudia Jürgen wrote: >>> >>>> Hi Mark, >>>> >>>> just don't drop the docs in the source code too soon as at some >>>> points >>>> they are more uptodate than the manual. Furthermore there are large >>>> chunks (submission process) missing in the manual. >>>> In my opinion it would be better to keep the docs (in another >>>> format, >>>> docbook or so) along with the source and populate a manual and other >>>> material based on this for releases. Docbook would give us the >>>> opportunity to work on i18n for the documentation. >>>> >>>> cheers >>>> >>>> Claudia >>>> >>>> >>>> Mark Diggory schrieb: >>>>> I recommend working with Brad to get this in to their loop. We're >>>>> getting ready to drop the html documentation in the source and >>>>> replace it with a PDF export from the Foundations documentation >>>>> processes. >>>>> >>>>> -Mark >>>>> >>>>> On Jul 21, 2008, at 1:04 PM, Tim Donohue wrote: >>>>> >>>>>> Scott, >>>>>> >>>>>> Touche.. :) Yea, that's an even better question. From what I've >>>>>> seen >>>>>> the HTML *seems* the most up-to-date...but, I no longer know what >>>>>> the >>>>>> definitive version is either. >>>>>> >>>>>> So, I'd agree with you. It'd be nice to have a *definitive* place >>>>>> where >>>>>> this documentation is going, and a means in which to submit >>>>>> documentation updates (like this one). >>>>>> >>>>>> - Tim >>>>>> >>>>>> Scott Phillips wrote: >>>>>>> Tim, >>>>>>> >>>>>>> That's a great question, what is the "normal" DSpace >>>>>>> documentation? >>>>>>> There's the presumably now out of date HTML in the source tree, a >>>>>>> word / >>>>>>> pdf document floating around, and then the wiki..... >>>>>>> >>>>>>> Scott-- >>>>>>> >>>>>>> >>>>>>> On Jul 21, 2008, at 2:00 PM, Tim Donohue wrote: >>>>>>> >>>>>>>> Nice job, Scott (and others who helped)! >>>>>>>> >>>>>>>> Now the obvious question: Can we get this "wrapped up" into the >>>>>>>> normal >>>>>>>> DSpace Documentation? :) >>>>>>>> >>>>>>>> - Tim >>>>>>>> >>>>>>>> Scott Phillips wrote: >>>>>>>>> DSpacers, >>>>>>>>> It's a funny thing, the DSpace Batch Import Format (of which >>>>>>>>> there >>>>>>>>> are two) are not documented anywhere other than looking at the >>>>>>>>> source code. We've run across the situation where a >>>>>>>>> department has >>>>>>>>> some content to put into the repository and the resources to >>>>>>>>> create >>>>>>>>> a batch import, but just don't know how to do it. To solve >>>>>>>>> this >>>>>>>>> problem, we've created a simple hand out to provide to a >>>>>>>>> programmer >>>>>>>>> or technical person in another department or group when they >>>>>>>>> want to >>>>>>>>> develop their own batch import script. While it doesn't cover >>>>>>>>> the >>>>>>>>> advanced topics, like registering bitstreams etc, nor dose >>>>>>>>> it go >>>>>>>>> over the package importer, it should solve the problem for the >>>>>>>>> vast >>>>>>>>> majority of cases where someone needs to create a batch >>>>>>>>> import. >>>>>>>>> I thought this might be useful to others out there, the only >>>>>>>>> other >>>>>>>>> resource on creating batch imports I was able to find is >>>>>>>>> Dorothea's >>>>>>>>> blog: >>>>>>>>> http://cavlec.yarinareth.net/2008/01/07/the-dspace-batch- >>>>>>>>> importer/. >>>>>>>>> Here is our handout: >>>>>>>>> https://www.tdl.org/documents/DSpaceBatchImportFormat.pdf >>>>>>>>> Scott-- >>>>>>>>> ----------------------------------------------------------------- >>>>>>>>> -- >>>>>>>>> ------ >>>>>>>>> >>>>>>>>> This SF.Net email is sponsored by the Moblin Your Move >>>>>>>>> Developer's >>>>>>>>> challenge >>>>>>>>> Build the coolest Linux based applications with Moblin SDK & >>>>>>>>> win >>>>>>>>> great prizes >>>>>>>>> Grand prize is a trip for two to an Open Source event anywhere >>>>>>>>> in the >>>>>>>>> world >>>>>>>>> http://moblin-contest.org/redirect.php?banner_id=100&url=/ >>>>>>>>> _______________________________________________ >>>>>>>>> DSpace-tech mailing list >>>>>>>>> DSpace-tech@lists.sourceforge.net >>>>>>>>> https://lists.sourceforge.net/lists/listinfo/dspace-tech >>>>>>>> -- >>>>>>>> Tim Donohue >>>>>>>> Research Programmer, Illinois Digital Environment for >>>>>>>> Access to Learning and Scholarship (IDEALS) >>>>>>>> University of Illinois at Urbana-Champaign >>>>>>>> [EMAIL PROTECTED] | (217) 333-4648 >>>>>> -- >>>>>> Tim Donohue >>>>>> Research Programmer, Illinois Digital Environment for >>>>>> Access to Learning and Scholarship (IDEALS) >>>>>> University of Illinois at Urbana-Champaign >>>>>> [EMAIL PROTECTED] | (217) 333-4648 >>>>>> >>>>>> -------------------------------------------------------------------- >>>>>> -- >>>>>> --- >>>>>> This SF.Net email is sponsored by the Moblin Your Move Developer's >>>>>> challenge >>>>>> Build the coolest Linux based applications with Moblin SDK & win >>>>>> great prizes >>>>>> Grand prize is a trip for two to an Open Source event anywhere in >>>>>> the world >>>>>> http://moblin-contest.org/redirect.php?banner_id=100&url=/ >>>>>> _______________________________________________ >>>>>> DSpace-tech mailing list >>>>>> DSpace-tech@lists.sourceforge.net >>>>>> https://lists.sourceforge.net/lists/listinfo/dspace-tech >>>>> --------------------------------------------------------------------- >>>>> ---- >>>>> This SF.Net email is sponsored by the Moblin Your Move Developer's >>>>> challenge >>>>> Build the coolest Linux based applications with Moblin SDK & win >>>>> great prizes >>>>> Grand prize is a trip for two to an Open Source event anywhere in >>>>> the world >>>>> http://moblin-contest.org/redirect.php?banner_id=100&url=/ >>>>> _______________________________________________ >>>>> Dspace-devel mailing list >>>>> [EMAIL PROTECTED] >>>>> https://lists.sourceforge.net/lists/listinfo/dspace-devel >>>> ---------------------------------------------------------------------- >>>> --- >>>> This SF.Net email is sponsored by the Moblin Your Move Developer's >>>> challenge >>>> Build the coolest Linux based applications with Moblin SDK & win >>>> great prizes >>>> Grand prize is a trip for two to an Open Source event anywhere in >>>> the world >>>> http://moblin-contest.org/redirect.php?banner_id=100&url=/ >>>> _______________________________________________ >>>> Dspace-devel mailing list >>>> [EMAIL PROTECTED] >>>> https://lists.sourceforge.net/lists/listinfo/dspace-devel >>> >>> ------------------------------------------------------------------------- >>> This SF.Net email is sponsored by the Moblin Your Move Developer's >>> challenge >>> Build the coolest Linux based applications with Moblin SDK & win >>> great prizes >>> Grand prize is a trip for two to an Open Source event anywhere in >>> the world >>> http://moblin-contest.org/redirect.php?banner_id=100&url=/ >>> _______________________________________________ >>> DSpace-tech mailing list >>> DSpace-tech@lists.sourceforge.net >>> https://lists.sourceforge.net/lists/listinfo/dspace-tech >> ------------------------------------------------------------------------- >> This SF.Net email is sponsored by the Moblin Your Move Developer's >> challenge >> Build the coolest Linux based applications with Moblin SDK & win >> great prizes >> Grand prize is a trip for two to an Open Source event anywhere in >> the world >> http://moblin-contest.org/redirect.php?banner_id=100&url=/ >> _______________________________________________ >> DSpace-tech mailing list >> DSpace-tech@lists.sourceforge.net >> https://lists.sourceforge.net/lists/listinfo/dspace-tech > > > ------------------------------------------------------------------------- > This SF.Net email is sponsored by the Moblin Your Move Developer's challenge > Build the coolest Linux based applications with Moblin SDK & win great prizes > Grand prize is a trip for two to an Open Source event anywhere in the world > http://moblin-contest.org/redirect.php?banner_id=100&url=/ > _______________________________________________ > DSpace-tech mailing list > DSpace-tech@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/dspace-tech > -- Tim Donohue Research Programmer, Illinois Digital Environment for Access to Learning and Scholarship (IDEALS) University of Illinois at Urbana-Champaign [EMAIL PROTECTED] | (217) 333-4648 ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ DSpace-tech mailing list DSpace-tech@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/dspace-tech
