Yes, but we need to draw a line in the sand and do so quickly, the Foundation and the Community need to.
a.) Agree on the approach b.) Eliminate all other possibilities for forking of the documentation. c.) Do so before we release 1.5.1 As 1.5.1 release coordinator. I will be drawing some of those lines as we approach the release. The first tentative line is that there will not be html documentation maintained directly the S.F. dspace SVN project (trunk and 1.5.x branches). This doesn't mean it couldn't reside somewhere else, for instance in the dspace-sandbox where more hands could be involved with it maintenance. This was an initial route we took, but those doing the work editing the documentation within the Foundation did not take advantage of it due to lack of knowledge with svn. Which in turn reflects the greater problem with having user support level documentation stored/ maintained in svn. -Mark On Jul 24, 2008, at 7:39 AM, Tim Donohue wrote: > 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 >>>>>>>>>> [email protected] >>>>>>>>>> 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 >>>>>>> [email protected] >>>>>>> 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 >>>> [email protected] >>>> 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 >>> [email protected] >>> 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 >> [email protected] >> 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 > [email protected] > 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 [email protected] https://lists.sourceforge.net/lists/listinfo/dspace-tech
