Mark Ramm wrote: >> I think these questions are very related with my GSoC project [1], and ideas >> like yours are welcome to make me work even more effectively during this >> summer :D >> >> With Sphinx we can create extensions that could generate metadata about >> versions, or develop reST directives to reference to others documentations >> using the right version. >> >> I didn't understand exactly how backlinks could be used... only to persist >> information about references? or create sections like 'see also'? > > I think it's important that frameworks like TG and Pylons have a > complete set of docs "under one roof" so to speak, because we need to > compete with projects that do that. (Rails and Django come to mind.) > But perhaps there are some solutions to this that work for everybody.
There's a lot of give on how the documentation for stuff like Paste, WebOb, and FormEncode is laid out. But there's always been something that's bothered me about projects with docs spewed over the internet. I'd really like to avoid duplicating those docs all over the place. And I don't think a change in domain name will stress out readers. The real concern is cohesive navigation, style changes that aren't jarring, and if there's any added features like comments then those should be consistent too. The one that I don't know how to solve is navigation. Backlinks mitigate the problem, but they aren't a complete solution, and repurposing content is just hard. And this isn't just an issue for these underlying projects, it's an issue with TG and Pylons as well, and any other complementary packages as well. Downloading a full set of documentation isn't a problem, and we don't need all the docs on the same domain name to do that. Ben had concerns about the reliability of the docs if there's multiple hosts involved. But I don't really care where my docs are hosted, so if Pylons or TG hosts the docs with a vhost I'm happy, and it's just as reliable as a single domain. Analogous to this discussion we have a mailing list problem, as I don't know where this conversation should occur. Let's at least try to keep paste-users copied. > Backlinks is one possibility, creating a "home base" for docs of > various kinds so we can have one true location for the WebOb docs > works. We can also get creative with no-follow on links and making > sure that the right pages get marked as private in robots.txt. Ben suggested this as well, so that at least google only sees one copy of any page. I think meta-no-index tags in the header would be the easiest way to do it. But then the core docs don't get any of the Page Rank love, and we just throw away the (substantial) benefit of linking in Pylons and TG docs. Also, any commenting we add to the docs will be badly confused if we mirror the docs a lot, because there won't be any one place to keep track of comments. (I guess that also relates to keeping comments on versioned docs, but I'm inclined to only allow comments on the current version of docs, or maybe on the devel version so long as there a warning to indicate what's appropriate to comment on, and a warning that comments are quick to get out of sync in that situation.) -- Ian Bicking : [EMAIL PROTECTED] : http://blog.ianbicking.org _______________________________________________ Paste-users mailing list [email protected] http://webwareforpython.org/cgi-bin/mailman/listinfo/paste-users
