>>>>> On 15 Jul 2003, "kfogel" == kfogel@collab.net wrote:
kfogel> This patch is a great idea, Paul, thanks for doing it.
My pleasure.
kfogel> Are there more specific URLs for these? If so, giving them
kfogel> here can save time (or just point to INSTALL, if they're in
kfogel> there).
I'll dig those up.
kfogel> Are these URLs given in some other document? If so, just
kfogel> point to that doc, IMHO. That way if we fix it in one
kfogel> place, it's fixed for all the others.
...
kfogel> This is all explained in INSTALL, right? Maybe just
kfogel> reference that.
...
kfogel> Basically, release managers have to be familiar with
kfogel> installing Subversion and running all combinations of 'make
kfogel> check'. They might as well get that familiarity the same
kfogel> way everyone else does, reading the same docs, etc...
...
kfogel> This is also a dup of information in INSTALL. Just
kfogel> reference it.
I wrestled with this back and forth for awhile. The problem I had
was that even with the cross referencing, finding this information in
the other docs quickly is rather a pain. I absolutely hate the idea
of redundant data, but at the same time, it makes figuring out how to
do a release more efficient. So, it comes down to a tradeoff between
long-term information management/maintenance and getting up to speed
on release management quickly.
On one hand, had these steps been spelled out for me, I think the last
release would have likely gone more quickly. On the other hand, I
wouldn't have learned nearly as much if they had. On the third hand,
I wouldn't have wasted nearly as much of yours and sussman's time :)
Perhaps what's needed is a review of the various INSTALL/BUILD/README
type docs which condenses the information into a more logical flow
that makes cross-referencing a little easier.
As you mentioned:
kfogel> these URLs given in some other document?
The problem is that this same information is needed in several places.
I found that to be true of a lot of information contained in
releases.txt. So, the thought I has was, can certain pieces of
information be coerced into m4 macros such that we can change it in 1
place, but it gets updated everywhere it's needed?
This would allow for having very explicit developer docs, while also
providing for ease of maintenance of these docs. The only down side
I can see is that in order to actually make use of these docs, you'd
be required at the very least, to ./configure and make (though,
perhaps we can create a new make target dev-docs?).
Thoughts/comments?
--
Seeya,
Paul
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Tue Jul 15 18:48:39 2003