Re: Git documentation at kernel.org

Jeff King [off-list ref] writes:

If there is interest in this, we would be happy to host the
documentation. Let me know if that is the case, and we can give it a
much better URL than schacon.github.com. However, I tend to think that
since the project is hosted[1] at kernel.org, the official documentation
site should be there as well.

kernel.org is probably the most "official" place for developers, but for
Git users, http://git-scm.com/ is most likely the best entry point. If
it were not for historical reasons, I think http://git-scm.com/docs/ or
so would be the most natural URL to host official docs.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

On Sun, Feb 12, 2012 at 11:04:23PM +0100, Matthieu Moy wrote:

Jeff King [off-list ref] writes:

quoted

If there is interest in this, we would be happy to host the
documentation. Let me know if that is the case, and we can give it a
much better URL than schacon.github.com. However, I tend to think that
since the project is hosted[1] at kernel.org, the official documentation
site should be there as well.

kernel.org is probably the most "official" place for developers, but for
Git users, http://git-scm.com/ is most likely the best entry point. If
it were not for historical reasons, I think http://git-scm.com/docs/ or
so would be the most natural URL to host official docs.

Good point. That is probably the best place to host it.

As far as historical reasons, perhaps the right answer is to put the
documentation where it makes sense to go _now_, and ask kernel.org to
issue http redirects for http://kernel.org/pub/software/scm/git/docs.

-Peff

Hey,

On Sun, Feb 12, 2012 at 2:25 PM, Jeff King [off-list ref] wrote:

quoted

kernel.org is probably the most "official" place for developers, but for
Git users, http://git-scm.com/ is most likely the best entry point. If
it were not for historical reasons, I think http://git-scm.com/docs/ or
so would be the most natural URL to host official docs.

Good point. That is probably the best place to host it.

As far as historical reasons, perhaps the right answer is to put the
documentation where it makes sense to go _now_, and ask kernel.org to
issue http redirects for http://kernel.org/pub/software/scm/git/docs.

I would be happy to set this up.  I'm currently in the process of
revamping the website and this is one of the things I'm planning on
doing anyways - not just hosting the generated docs, but also making
them searchable and whatnot.

Actually, as long as I'm on this, what do people think about git-scm
hosting the wiki as well?  As far as I can tell, it was down for
months and now it's back in some sort of weird read-only state.  If I
imported everything into a different wiki and hosted it on git-scm
would that be acceptable?

Also, something that I realized I am not willing to maintain any more
is the Git Community Book. It was an experiment at reorganizing some
of the docs, but instead I spent my time on Pro Git, which is CC
licensed.  Would anyone object to me removing the community book from
the git-scm site and more tightly integrating the Pro Git content?
It's more up to date and better content, I feel - I would rather have
one book to maintain than two.  However, since it is a commercial
product (albeit a Creative Commons licensed one), I wasn't sure if
people would have an issue with it.

Scott

On Sun, Feb 12, 2012 at 03:04:59PM -0800, Scott Chacon wrote:

quoted

Good point. That is probably the best place to host it.

As far as historical reasons, perhaps the right answer is to put the
documentation where it makes sense to go _now_, and ask kernel.org to
issue http redirects for http://kernel.org/pub/software/scm/git/docs.

I would be happy to set this up.  I'm currently in the process of
revamping the website and this is one of the things I'm planning on
doing anyways - not just hosting the generated docs, but also making
them searchable and whatnot.

That sounds great to me. I'd like to be link-compatible with the old
kernel.org docs section (even if through redirects) so that old links
work (assuming kernel.org gives us a wholesale redirect).  Which means
importing all of the docs for released versions. I don't know if the old
kernel.org doc tree was saved anywhere, but if I understand correctly,
they are identical to what's in the "git-htmldocs" repository (which I
_thought_ Junio wasn't going to keep updating, but it seems pretty up to
date).

Actually, as long as I'm on this, what do people think about git-scm
hosting the wiki as well?  As far as I can tell, it was down for
months and now it's back in some sort of weird read-only state.  If I
imported everything into a different wiki and hosted it on git-scm
would that be acceptable?

I'd really love it if the wiki was converted to something that was
git-backed. But I suspect some people might complain about switching off
of mediawiki. IIRC, gollum supports some mediawiki syntax, but I don't
know how much conversion work there would be.

Also, something that I realized I am not willing to maintain any more
is the Git Community Book. It was an experiment at reorganizing some
of the docs, but instead I spent my time on Pro Git, which is CC
licensed.  Would anyone object to me removing the community book from
the git-scm site and more tightly integrating the Pro Git content?
It's more up to date and better content, I feel - I would rather have
one book to maintain than two.  However, since it is a commercial
product (albeit a Creative Commons licensed one), I wasn't sure if
people would have an issue with it.

I can't remember anybody mentioning the Git Community Book here in the
past few years. New users typically come with a "I read this in Pro Git
and I don't understand..." question, and experienced users recommend or
link to Pro Git. So I think the world would be a less confusing place
with just the one source.

-Peff

On Sun, 2012-02-12 at 17:25 -0500, Jeff King wrote:

As far as historical reasons, perhaps the right answer is to put the
documentation where it makes sense to go _now_, and ask kernel.org to
issue http redirects for http://kernel.org/pub/software/scm/git/docs. 

I think that should be fine, unless John objects. The easiest would be
to preserve the same directory structure, so we do a dir-level redirect
instead of creating one-off redirects for each page.

Best,
-- 
Konstantin Ryabitsev
Systems Administrator, Kernel.org
Montréal, Québec