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 : ianb@??? : http://blog.ianbicking.org
_______________________________________________
Paste-users mailing list
Paste-users@???
http://webwareforpython.org/cgi-bin/mailman/listinfo/paste-users
