[Q&A] Documentation URL in answers ?

asked 2015-11-30 10:01:57 -0600

pklab

4284 ●7 ●30 ●60

I'm totally agree with @StevenPuttemans and others in OpenCV 3.0 doxygen documentation still very counter intuitive

In the mean time, which URL for the documentation we have to use while answering ?

Example for cv::circle

old doc url (very nice and persistent)

http://docs.opencv.org/modules/core/doc/drawing_functions.html#circle

automatically redirected to 2.4.11 version (redirection is nice too)

http://docs.opencv.org/2.4.11/modules/core/doc/drawing_functions.html#circle

link to current 3.0.0 Doxygen

http://docs.opencv.org/3.0.0/d6/d6e/group__imgproc__draw.html#gaf10604b069374903dbd0f0488cb43670

current 3.0.0 Sphinx

http://docs.opencv.org/3.0-last-rst/modules/imgproc/doc/drawing_functions.html#circle

Referring to the example:

Which URL we have to use in answers ? I suppose current master but...
Will anchors like #gaf10604b069374903dbd0f0488cb43670 survive in the future ?
What about future of path /d6/d6e/group__imgproc__draw.html for Drawing Functions ?

In any case I would suggest better URL facing... is this possible with Doxygen ?

Comments

The "current" 3.0.0 Sphinx is long outdated (Last updated on Dec 30, 2014), so I would avoid that.
If we want to unify things, I'd go with http://docs.opencv.org/2.4/... and http://docs.opencv.org/master/...as they're the most frequently updated (http://docs.opencv.org/3.0.0/ last update on Jun 3 2015)
Personally, I like to point to 2.4.x docs whenever possible for various reasons: 1) much intuitive docs, 2) references to Python functions, 3) same concerns as you about url persistence in 3.0 docs. I do however refer to 3.0.0 docs for tutorials, because I feel they are better structured (and obviously more updated)

LorenaGdL ( 2015-11-30 10:37:23 -0600 )edit

Maybe we should have a wait and see how @mshabunin thinks about this? :)

StevenPuttemans ( 2015-12-01 03:03:25 -0600 )edit

add a comment

answered 2015-12-01 04:51:33 -0600

mshabunin
1927 ●10 ●31

updated 2015-12-01 04:55:10 -0600

Released documentation (/3.0.0, /2.4.11, etc.) will not be modified in future, thus you can safely refer to it. Nightly documentation (/master, /2.4) is not as stable and will change.

Comments

Thank you!

StevenPuttemans ( 2015-12-01 05:58:49 -0600 )edit

Well, I like 2.4 docs but I think is non sense to continue to use it in new answers.

So, despite of in my opinion doxygen urls are not friendly, we could unify things following @mshabunin scheme on 3.0.0 doc. Opinions ?

pklab ( 2015-12-02 10:18:12 -0600 )edit

@pklab I would actually rather give people the latest possible link. 3.0.0 docs are way outdated. I rather have someone re-explaining or re-asking the correct link, then passing outdated information.

StevenPuttemans ( 2015-12-03 02:02:40 -0600 )edit

I agree with @StevenPuttemans. Stable releases are so sparse in time that docs become outdated pretty soon. Moreover, imagine the following situation: someone answers with a /3.0.0/ link to a function F today. Six months later, 3.1 version is already avaible and some other user reads the question. It is more likely that F function has suffered some standalone docs modification than the url path is no longer usable (because as Maksim said, it depends on the group, so I guess is unlikely for a function to change group). Also, this is a fact: if the URL doesn't work, the user will ask again with no doubt; if the URL is outdated, user won't notice it and he will probably miss new features or insights about function use/parameters

LorenaGdL ( 2015-12-04 04:22:04 -0600 )edit

add a comment

[Q&A] Documentation URL in answers ?

Comments

1 answer

Comments

Links

Question Tools

Stats

Related questions

[Q&A] Documentation URL in answers ? edit

Comments

1 answer

Comments

Links

Question Tools

Stats

Related questions

[Q&A] Documentation URL in answers ?