Re: [gentoo-dev] Projects and simple guides

[Brian Harring]

Sending this to the ml, tom already has heard the reasons but throwing 
them out for others to comment on...

On Mon, Jan 09, 2006 at 04:47:57PM +0000, Tom Martin wrote:
> > I realize this doesn't address the *rest* of what you said, though...

<snip>

> These little 'howtos' are potentially very short, and guideXML would be
> overkill. RST is absolutely perfect for this kind of thing: quick and
> easy to write, powerful, and legible in raw form. It's also easily
> converted to any number of other formats.
Agreed.

> A new CVS repository containing these little howtos that is accessible
> with viewcvs would be perfect, if you ask me. There would be proper
> version control on the files and they would be read/write for
> developers and read-only for users (otherwise the potential of
> vandalism etc. is too high). This is, in my opinion, how things should
> be for these simple developer guides.
disagree. :)

Note my comments about allowing non gentoo personnel to modify the 
docs.  I'm not minting half devs just so they can do some doc work, 
nor is it efficient for trusted devs to be passing patches through me 
just because they haven't yet been around long enough where we mint 
'em.


> The whole wiki-for-everything idea really annoys me. It forces
> a web browser on me, and this is particularly naff when it comes to
> editing. It's also really bland and boring, and completely unoriginal.

Note that what's being pushed here is the desire for a faster model of 
doc developing;

GDP/guidexml docs are good for long term stable docs.

They suck royally however, if we're talking about developmental docs 
for portage where things move quickly.  Less work required to maintain 
the documentation, higher chance the docs will actually be up to 
date/maintained.  Note that's my opinion, I don't dislike guidexml, I 
just prefer to not dink around with it for docs that are going to be 
rapidly changing.


> I still haven't fixed the other two points Brian mentioned, but I don't
> really think they're all that serious. If a user sees an omission, he
> can drop a mail to the guy who wrote the guide. There's really no
> reason to file bugs for anything like this.

We're not talking about a guide here- two scenarios.

flameeyes rapid development of docs, improving the quality- area to 
hash out the doc before slapping it up in official docs (and no, 
labelling it unofficial doesn't fly when we're talking about 
initial hammering out of the doc).

Essentially, a chalkboard/whiteboard for projects- communal scratchpad 
of what the current issues are (and I mean *current*, that day), 
proposals for apis, use scenarios, rough design documents.

We could (and do) do this via devspace, but that suffers the exact 
issue I'm after addressing- not everyone involved can modify it (for 
devspace, only one person can modify it).

> Allowing universal r/w is
> asking for vandalism. As for the third point -- concurrency -- this is
> exactly what any VCS is supposed to fix. We live with it with the
> tree's CVS, I'm sure we can live with it for this.

Where exactly did I ask for universal r/w?  I've seen a lot of args 
against this based upon "joe idiot will screw up the page".  What I'm 
after is non gentoo personnel capable of handling the docs- does that 
mean everyone?  No.  It means people not minting people just so we can 
have them do a bit of doc work, essentially, nuking the overhead.

Again, vcs is worthless if you don't have access to it.  Non gentoo 
folks do not have access to the vcs, thus we're right back to my point 
for why a wiki is useful- we don't have to mint a couple dozen part 
time contributors as devs just so they can do their work.

Proposals/alternatives thus far are basically reinventing wiki's, just 
slower.  That's kind of a sign that people dislike wiki software 
they've seen- I've yet to see anyone level arguement against the model 
of doc development I'm after however.

So... if the core need isn't an issue, wth should we reinvent the 
wheel and create our own wiki analog?

~harring