[Twisted-Python] Docs HTML suggestion/request for moving between versions.
Lately, I've taken to finding Twisted docs by writing:
twisted.internet.task.Cooperator
...into the Chrome bar'o'magic and hitting return to get the Google hit. This is great, except that the resultant Google hits almost always point me to the 8.2.0 HTML docs. 2nd hit is (currently) 11.0 docs.
Obviously it's tricky to force Google to put "current" at the top! But could we maybe have a little <select> dropdown in the top-right that shows the version, and lets you pick a new one and have the page reload?
It strikes me that this would be useful in general, for flicking back and forward between two versions of the docs page for a given method/API.
On 10/26/2011 11:29 AM, Phil Mayers wrote:
Obviously it's tricky to force Google to put "current" at the top! But could we maybe have a little<select> dropdown in the top-right that shows the version, and lets you pick a new one and have the page reload?
Other possibilities:
- Add a big yellow "this is for a prior version, click here to see the latest version of this page" with a direct link to the same page in the current documentation set.
- Make a symlink called "current" or "latest" that points the latest release and use robots.txt to prohibit search engines from indexing the version-specific doc sets. Google's "sitemap" feature might be useful here, I've never used it and I don't know if it actually changes search result priorities.
Both of these are of course compatible with your original suggestion, so implementing all three would be possible and useful. Studying other projects to see how they deal with this could be insightful, but for example PostgreSQL has the same problem -- even though they have a 'current' symlink, the top result for 'postgresql truncate command' is from 8.3 which is three releases out of date.
On 26 Oct, 03:29 pm, p.mayers@imperial.ac.uk wrote:
Lately, I've taken to finding Twisted docs by writing:
twisted.internet.task.Cooperator
...into the Chrome bar'o'magic and hitting return to get the Google hit. This is great, except that the resultant Google hits almost always point me to the 8.2.0 HTML docs. 2nd hit is (currently) 11.0 docs.
Obviously it's tricky to force Google to put "current" at the top! But could we maybe have a little <select> dropdown in the top-right that shows the version, and lets you pick a new one and have the page reload?
It strikes me that this would be useful in general, for flicking back and forward between two versions of the docs page for a given method/API.
I've updated http://twistedmatrix.com/documents/8.0.0/api/ - compare it to the old http://twistedmatrix.com/documents/old-8.0.0/api/ for problems, please. If it looks good, I can update all the other versions of the API documentation as well.
If you have style suggestions, please submit them as merge proposals to lp:~twisted-dev/pydoctor/twisted-templates-2.
Thanks, Jean-Paul
On 03/11/11 12:40, exarkun@twistedmatrix.com wrote:
I've updated http://twistedmatrix.com/documents/8.0.0/api/ - compare it
Cool, that looks good, thanks!
On 3 Nov, 01:04 pm, p.mayers@imperial.ac.uk wrote:
On 03/11/11 12:40, exarkun@twistedmatrix.com wrote:
I've updated http://twistedmatrix.com/documents/8.0.0/api/ - compare it
Cool, that looks good, thanks!
Thanks for the review. Since I didn't hear anything else, I went ahead and switched over all versions of the documentation to have this feature.
Jean-Paul
participants (3)
-
exarkun＠twistedmatrix.com -
Michael Tharp -
Phil Mayers