Forum OpenACS Development: Online docs need revision date and CVS $Id$ tag

Collapse
10: Online docs need revision date and CVS $Id$ tag (response to 1)
Posted by Andrew Piskorski on 11/26/02 06:04 AM
Vinod, I'm not sure precisely why, by the two versions of your Oracle install docs online at openacs.org, /doc/oracle.html and /doc/openacs-4/oracle.html are not the same! I believe /doc/oracle is newer, but there is no way to tell this by looking at the document.

So I pulled the latest version of the doc from CVS (currently rev. 1.8.2.2 in this case), but I still have no good way to know just which old version I was looking at on the website.

Suggestion: All static documents should include both a "Last Revised" date indicating the last time a human being revised the document and substantially changed it (and remembered to update the date), and and embedded CVS "$Id$ tag so we can see precisely what version the document is. Of the two, the CVS Id tag is more important, but I think it's worth having both.

Collapse
11: Re: Online docs need revision date and CVS $Id$ tag (response to 10)
Posted by Vinod Kurup on 11/26/02 07:32 AM
Hi Andrew,

How did you find /doc/oracle.html? In any case, both are out-of-date at the moment. There is a CVS ID tag on both documents, but it's at the bottom of the doc. Is that sufficient?

I know Jeff mentioned that he might set up a cronjob to regenerate the docs, but I'm not sure if he's done this yet. If not, I agree with him that it is a great idea!!

As an update, I have committed all the changes that I mentioned above. I also added a change that Jeff and Roberto suggested (I think?) to include a link back to the openacs.org website on all doc pages. That way, comments on locally installed pages can easily be placed on the openacs.org website. Of course, the version of the docs that is *actually* living on the openacs.org website should not have this link, cuz it would just be confusing. So, that part of the XSL stylesheet should be commented out on openacs.org.

Collapse
12: Re: Online docs need revision date and CVS $Id$ tag (response to 11)
Posted by Andrew Piskorski on 11/26/02 07:48 AM
To get to /doc/oracle.html, from openacs.org, click on Documentation for this Installation of OpenACS, Unix Installation Guide, Install Oracle 8.1.7, and there you are.

CVS Id tag at the bottom? There is? Ah... Yes, sorry, you are correct, I missed it. It's in a somewhat odd location though, a bit hard to spot. It would be better in either the header or footer of the document, or both. I personally like putting it in the the lower right corner of the footer, but as long as it's consistent I don't see any real difference. But the very most important thing is that it's there, somewhere - which you'd already done.