Thread: CVS docs referencing externals
When fixing the fact that the new cvs docs (how to pull with rsync) in HEAD refer to the wrong hostname for rsync, I (or rather, Dave, during our discussions) noticed two external references: http://developer.postgresql.org/pgdocs/postgres/cvs.html refers with a link to the developer wiki, and http://developer.postgresql.org/pgdocs/postgres/rsync.html refers to the buildfarm instructions. First of all, neither of these URLs are guaranteed to be stable. Second, should we really be referring to external URLs for such information? Wouldn't it be better to include a version of the text directly in our docs, so people can actually read it if these URLs/contents change? //Magnus
Am Montag, 6. August 2007 09:58 schrieb Magnus Hagander: > First of all, neither of these URLs are guaranteed to be stable. Second, > should we really be referring to external URLs for such information? No. > Wouldn't it be better to include a version of the text directly in our > docs, so people can actually read it if these URLs/contents change? Yes. -- Peter Eisentraut http://developer.postgresql.org/~petere/
On Mon, 6 Aug 2007, Magnus Hagander wrote: > http://developer.postgresql.org/pgdocs/postgres/cvs.html refers with a link > to the developer wiki This weekend I was already planning to move the developer's wiki PG/MySQL document to techdocs. Depending on how smoothly that goes, I planned to see if it was straightforward to move the more complicated CVS page to there as well. Would that give the content a sufficiently stable URL to refer to? > http://developer.postgresql.org/pgdocs/postgres/rsync.html refers to the > buildfarm instructions. One loose end in the CVS documentation on the developer's wiki is to make sure it has completely assimilated everything from the buildfarm document on this topic, so that dependency can drop altogether once I finish that. > Wouldn't it be better to include a version of the text directly in our > docs, so people can actually read it if these URLs/contents change? Hostnames change, suggested practices improve. When you're talking about accessing a CVS repository, there's little value in knowing how things used to be if they aren't like that anymore. If the URL is stable enough, I'd ask why worry about keeping around old versions? This particular content is just fluid enough still that I'd hesitate to do the more complicated conversion into the standard documentation format, which then requires a) periodically duplicating edits/recoverting to keep the two versions in sync or b) only keeping the docbook version and needing a CVS commit to make any changes. -- * Greg Smith gsmith@gregsmith.com http://www.gregsmith.com Baltimore, MD
Greg Smith wrote: > On Mon, 6 Aug 2007, Magnus Hagander wrote: > >> http://developer.postgresql.org/pgdocs/postgres/cvs.html refers with a >> link >> to the developer wiki > > This weekend I was already planning to move the developer's wiki > PG/MySQL document to techdocs. Depending on how smoothly that goes, I > planned to see if it was straightforward to move the more complicated > CVS page to there as well. Would that give the content a sufficiently > stable URL to refer to? I wouldn't bother with the CVS docs - they're not really aimed at end users, but the very people for whom the wiki is there. Regards, Dave.