Re: Requirements for Documentation System

--- Paul M Jones <pmjones@ciaweb.net> wrote: > On Apr 12, 2004, at 5:48 PM, Stefan Neufeind wrote: > > > On 13 Apr 2004 at 0:36, Cipriano Groenendal wrote: > > > >>>>>>>> 5. Fast turnaround between edits and > displayed results. > >>> Agreed. Let us say we are talking about a > trusted team, as per the > >>> above paragraph describing the PEAR-DEV problem. > Are we OK for > >>> "instantly" under that assumption? > >> With a roll-back in place, this would be a Good > Thing(TM) yes. > ... > > Oh, in that discussion I see a small problem: > Instant updating versus > > versioning. Imho instant updating while editing > should be restricted > > to a "Preview"-button, and clicking on "Save" > should be avoided until > > reasonable changes have undergone - otherwise we > would end up with > > multiple versions just for adding a word and then > thinking it might > > just be better to remove it again or something > :-)) > > Add new requirement: Ability to preview the edited > document (perhaps > multiple times) before saving or committing it. Indeed that will be useful. We already have a solution in the works: Livedocs. I have experimented doing this with Livedocs and works well for editing needs. > Add new requirement: Ability to distinguish between > versions of a > document. (This kind of folds into the "roll-back" > requirement.) Yep, and that's what a versioning control system brings to the process. Be it CVS, Subversion or even good old RCS, tech solutions exists and are in place (cvs.php.net). So that part of the requirements is more or less fulfilled. > > > Sorry, this mail was about techniques (CVS) - but > I think we should > > already consider if we can use the existing > backend somehow, or if it > > really needs replacement. > > It's OK (this time! ;-). You bring up an important > concept about this > process. > > The idea here is *not* to bash the current system. > There are certain > to be good and wonderful things about the current > state. > > The point here is to find out what we need. Then, > after we have the > "perfect list" we can propose solutions, everything > from "scrap it all" > to "modify in-place" to "keep it as it is." > > Nobody has actually done a requirements list, so > everybody has their > own idea of how things should be. If we can agree > on a set of goals, > we can have a common framework for discussion on how > to reach those > goals. Agree, PEARDOC stands as it is because it was an effort that evolved from the experience of PHPDOC. Making a change in the system will need more than just a set of requirements, will need a "sit down and code it" approach no matter what changes are planned. BTW, it is a good thing (TM) that Paul brought this up for discussion. Re-evaluation of what we do is healthy. ===== --- Jesus M. Castagnetto <jmcastagnetto@php.net> __________________________________ Do you Yahoo!? Yahoo! Tax Center - File online by April 15th http://taxes.yahoo.com/filing.html