Re: Requirements for Documentation System

> Paul says that package owners who are not members of PEAR-DOC should be > able to edit their package docs, and not the docs of packages they do > not own, but further discussion may be needed (Arnaud?). I think pear-dev, qa, doc groups should be able to make any changes. If something goes amiss it should be easy to reverse the situation. Keeping too tight a workflow will prevent more than encourage imho. > > 3. Easy to learn the markup to lower barriers to entry (docs are less > > sexy than code, let's make it easy to get into them ;-) > > No comments thus far. Well, I think several ways should be possible. I mean, you prefer a text editor and a browser, I prefer openoffice, so I think the system should be able to accept several ways to contribute documentation. We want a system which makes it easy for people to contribute so the system shouldn't be too strict. > > 4. Easy to translate the document source to multiple output formats, > > targets, and languages. > > No comments thus far. That a definite yes, multiple outputs/layouts should be made easy to obtain. > > 5. Fast turnaround between edits and displayed results. > > No comments thus far. Yes, the current situation shows how much this annoys people to wait a week for the result to show up on the site or the n minutes it takes to build the manual. Modifications should be visible pretty quickly. > > 6. A comment system so that users who are not allowed to edit directly > > can still be heard within context. > > No comments thus far. This a feature that has been popping up for a while and it's very important to have that. As Tim O'Reilly was pointing at Fosdem, one of the driving forces of Amazon is the number of user reviews available. Those reviews are one the biggest advantages of Amazon over its competitors. It should be the same for PEAR documentation. Arnaud.