documentation still points to Google bug-tracker

[nicklas]

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

[robe]

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?)

[nicklas]

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

[robe]

Fixed at r4688 for 1.3

[nicklas]

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

[robe]

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)

[kneufeld]

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

[nicklas]

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.

[robe]

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)

[kneufeld]

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

[nicklas]

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 :-)