What is interesting about this is that the full source code of the e-book is also made available here and you can look it at it up close and personal by checking it out to your local file system.
git clone https://github.com/progit/progit2.git
Well, to get straight to the point, since some people have expressed interest in getting documentation in shape, but the whole thing is not very well structured for collaboration at the moment, I have a simple modest (and actionable) proposal:
Let us (without further ado) just copy-cat exactly what this Chacon dude (and his collaborators) did with that Pro Git book.
I mean, my impression is that this is a pretty intelligent, competent group of people behind that, so the way they decided to structure this is probably sensible, and it is not likely that we would come up with any structure significantly better by discussing this ad nauseam. So, again, let’s just copy what they are doing.
Oh, and here are a couple of observations. The above refers to the second edition of the book. In that second edition, they use AsciiDoc as their canonical text format. For the first edition they used Markdown. You can see that in the (now archived) repository that they had going for the first edition of the book: GitHub - progit/progit: Pro Git Book Content, 1st Edition - This content is deprecated. See 2nd edition at [progit2](https://github.com/progit/progit2)
So, I would make the point that the fact that these people switched from Markdown to AsciiDoc despite the fact that Markdown is more popular and better known, in my view, strongly suggests that AsciiDoc is a better tool for this kind of project. You know, they realized that they needed some sort of plain text lightweight-markup sort of format as their canonical format for storing text and Markdown was the obvious choice, but then they hit problems with that and on the second pass, migrated to AsciiDoc.
EXCEPT… that we don’t have to go through those steps. We simply benefit from their prior experience and go straight to AsciiDoc!
So, I think this provides a pretty good overarching template to structure our documentation efforts. I would also make the point that any piece of documentation we work up should be separately usable as:
- An article on Dzone (or similar venue)
- A more or less self-contained Wiki article
- A chapter in our overall documentation effort that could be turned pretty easily into a book (e-book or dead tree) assuming that we follow the basic template of the GIT book.
Also, they’ve got it pretty clearly structured for people to come in and localize (a.k.a. translate) the content. I was really quite impressed at the list of languages that have (according to them) full translations!
Full translation available in
Ain’t that something? That somebody translated the entire book into French or Russian or Mandarin Chinese, say, that’s hardly that surprising. (Even so, it’s maybe somewhat surprising.) But that people translated this book into… Bulgarian… Ukrainian… especially the latter, since surely everybody who reads Ukrainian also reads Russian anyway. But… Azerbaijani(!!!) Tagalog… (WTF??!! Tagalog? Holy shit!!!)
Or are these basically machine translations? Somebody really sat down and translated that whole book by hand start to finish to Tagalog???
But well… that’s all a tangent. Again, I think we should just copy-cat the basic set-up and structure of this Pro-git book and get that going. I mean, there are people out there willing to put some work into things but it’s important to have a very clear structure so that people can contribute, no?