On Sat, 23 Jun 2001, brian moseley wrote:
> On Sat, 23 Jun 2001, Doug MacEachern wrote:
>
> > i'm pretty sure cvs allows access control so certain
> > people can write to docs/ but not ../
>
> it doesn't actually; you have to rely on unix permissions.
>
> would you really trust somebody to write docs that you
> wouldn't trust to write code? i wouldn't. so i don't think
> it should be a concern.
Of course you should trust somebody to write docs. If you don't you will
end up with little or no documentation at all. That's why we have cvs
commit emails, so you can review the commits, which is less time consuming
than actual writing.
This is also a non-issue completely for the user guide, where someone who
is core developer won't do a good job, because too many things are obvious
to him, and which are completely not obvious to newbies and people with
less knowledge. That's very important to let other people do this
important part of the documentation. Of course these people shouldn't have
an access to the code commit at large.
Look at the httpd-docs project, which is quite successful and it's
virtually separated from httpd. People who aren't necessarily committing
to httpd rep, do have cvs commit perms to the httpd-docs rep.
> > the other reason for the split is if we want to release
> > docs more often than the rest of the distribution. if
>
> why exactly would one release docs separately? i don't see
> it happening in reality. keep them in the core module.
given that code releases are very infrequent, as we have seen with 1.x
series, releasing the updated documentation more frequently is important
especially for doc fixes. You cannot release new code without updating
docs, but you can release new docs without updating the code :)
> > the other question is should docs for modules live
> > inlined in the .pm's or be in
> > docs/pod/lib/Apache/FooModule.pod ? i would think the
> > latter so the pdf and other doc magic stas plans can be
> > applied to the module docs.
>
> i highly prefer having module doc inline. and i mean inline,
> interspersed amongst subs, so i can see the doc for a sub when i'm
> looking at its code. i get annoyed when i have to scroll to the bottom
> or open a second window to look at the doc for a sub :)
+1
As I said in my previous email, that shouldn't be of a problem for the
docs project. We can mix and match inline pods and external pod files. All
we need is to try to be consistent.
_____________________________________________________________________
Stas Bekman JAm_pH -- Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide http://perl.apache.org/guide
mailto:[EMAIL PROTECTED] http://apachetoday.com http://eXtropia.com/
http://singlesheaven.com http://perl.apache.org http://perlmonth.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
