Opened 14 years ago

Closed 14 years ago

Last modified 14 years ago

#275 closed defect (fixed)

documentation still points to Google bug-tracker

Reported by: nicklas Owned by: pramsey
Priority: medium Milestone: PostGIS 1.3.7
Component: postgis Version:
Keywords: Cc:

Description

All documentation still points to Google bug-tracker in chapter "Reporting Software Bugs" ch 7 or 9

Change History (10)

comment:1 by robe, 14 years ago

Milestone: postgis 1.5.0postgis 1.4.1
Resolution: fixed
Status: newclosed

fixed at r4683, r4684, r4685 (for both 1.4 branch and 1.5 trunk)

Nicklas,

I couldn't find the same error in chapter 7 (just saw it in chapter 9). Where do you see it in chapter 7 (or you referring to 1.3 documentation?)

comment:2 by nicklas, 14 years ago

Yes, I meant 1.3, that's why the "or" :-) /Nicklas

comment:3 by robe, 14 years ago

Milestone: postgis 1.4.1postgis 1.3.7

Fixed at r4688 for 1.3

comment:4 by nicklas, 14 years ago

Does the current documents have to point wrong until next release?

comment:5 by robe, 14 years ago

Yes. Well maybe our wording should change on the doc page (since we really have stable in the development snapshots).

http://www.postgis.org/documentation/ To be something like:

  • Released Versions (change from Stable Releases)

o 1.4 [html] [pdf] (v1.4.0) o 1.3 [html] [pdf] (v1.3.6)

  • Development Snapshots

o 1.5 [html] [pdf] (rev4690) o 1.4 [html] [pdf] (rev4685) o 1.3 [html] [pdf] (rev4688)

comment:6 by kneufeld, 14 years ago

Updated as per Regina's suggestion (though it was worded that way to emphasize that development snapshots are not stable).

Nicklas, can you explain this further? I don't follow. "Does the current documents have to point wrong until next release? "

— Kevin

comment:7 by nicklas, 14 years ago

Kevin, what I mean is that the released documentation here:
http://postgis.org/documentation/manual-1.4/ch09.html#id2621924
still points to google bug-tracker.

BTW, why do we have minor release documentation. Since there should be no difference in fuctionality between minor releases the latest snapshot ought to be the best document. Isn't that the great thing about online-documentation that it is up to date.

comment:8 by robe, 14 years ago

Nicklas,

You have a point. I think maybe we should just drop the micro from our documentation and have it called manual-1.4SVN

However I still think our released documentation should point at the actual released version.

Here is why and I'm going to explain it really badly.

A released freeze provides us (and package managers) a checkpoint as to what we can expect most everyone will be using so we aren't dealing with slight differences in things. The non-released stuff also has stuff subject to change — like it has the link to unreleased 1.4.1 tar which would be confusing if you are assuming its the official doc.

If you think about documentation like any other kind of source code, it is prone to the same problems. We could accidentally cut out whole sections or put in stuff for debate etc, because we aren't going to be quite as careful, knowing we will recheck it later before release. True it does have an advantage being online, but not everyone reads it online.

Its the same reason why we still offer the 1.4.0 released version and everyone isn't rushing to use 1.4.1SVN even though it in theory is a more stable product than 1.4.0 RTM because it has all bug fixes for 1.4 and not much else)

comment:9 by kneufeld, 14 years ago

I concur with Regina's comments regarding the release docs.

Good catch with the micro in the developmental snapshot urls, Nicklas. I can probably clean that up in my spare time.

— Kevin

comment:10 by nicklas, 14 years ago

sorry for confusing by mixing major, minor micro, but you understood me perfectly right anyway.

I see the logic in handling the documentation like the rest of the source code and it is reallt not a big issue since there is very rare to find "bugs" in the documentation.

Kevin, I don't think I catched anything at least not that I am aware of, but I mixed concepts about major, minor and micro. But if I pointed out something without knowing it, it's great :-)

Note: See TracTickets for help on using tickets.