git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Jon Forrest <nobozo@gmail.com>
To: "Jakub Narębski" <jnareb@gmail.com>
Cc: git <git@vger.kernel.org>
Subject: Re: [ANN] Pro Git Reedited 2nd Edition
Date: Sun, 24 Jul 2016 11:41:24 -0700	[thread overview]
Message-ID: <89e0a631-6396-e56e-0c1d-37acdbf8eda4@gmail.com> (raw)
In-Reply-To: <5795087C.4010503@gmail.com>



On 7/24/2016 11:27 AM, Jakub Narębski wrote:

> In my opinion being able to view it online has its advantages.
> Even casual reader can check it, and point errors or offer suggestions
> for improvements.

Absolutely. Now that I've finished the editing I'll look
into that.

> I think you can share a folder instead, and this would be stable.
> Alternatively, when updating the book you could update the link
> in the GitHub repository description and/or the README for the
> fork.

I'll check your folder idea. If that's correct then that would
be an excellent way to do it. I had already thought of updating
the README but I'm not sure if this would be sufficient.

> Well, https://git.github.io/htmldocs/git.html is on GitHub Pages
> (for a project, that is in https://github.com/git/git.github.io repo
> that is also used for Git Rev News), and it obviously uses AsciiDoc.

I'll check that.

> You can use Jekyll, or you can just upload HTML, as described
> in https://help.github.com/articles/creating-project-pages-manually/
> (this one is for per-repo GitHub Pages, i.e. using orphan branch
> gh-pages, not a special named repository like e.g. git.github.io).
> After each change / release you would need to rebuild HTML version
> and upload to GitHub pages. This can be automated with hooks.

I'll also look into that.

These are all great suggestions, which I appreciate. I didn't
do any of this for the 1st edition, which, in retrospect,
was probably a mistake.

> BTW. I thought that Pro Git used Markdown, not AsciiDoc?

Nope. Asciidoc. See
https://medium.com/@chacon/living-the-future-of-technical-writing-2f368bd0a272#.fdhsp0zgj

> All right. One issue I have after browsing through changes is that
> description of changes and their granularity is severely lacking.
> "A few more very minor changes.", "More piddly changes.", "should have
> included this in last commit" are not good commit messages.

You're absolutely right. I probably should have squashed those commits.
Those comments aren't really intended for public consumption.
Since I made many changes per commit, I really couldn't give an
instructive commit message.

Now that this edition is done, I plan on following good commit
practices in the future.

> If I find time to comment on changes, I would do that on GitHub,
> commenting / adding notes on changes there (like the one I posted
> as demo:
>   https://github.com/nobozo/progit2/commit/43ae203c2ccf1a017153de1b41a8c47eb166dba1#commitcomment-18372006

That would be great. I think I'm setup for that now in my GitHub
repo for that book.

Jon


  reply	other threads:[~2016-07-24 18:41 UTC|newest]

Thread overview: 13+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2016-07-24  4:07 [ANN] Pro Git Reedited 2nd Edition Jon Forrest
2016-07-24  9:00 ` Jakub Narębski
     [not found]   ` <6f7eea6b-2446-5740-cbec-141d71a33ea1@gmail.com>
2016-07-24 17:19     ` Jakub Narębski
2016-07-24 17:34       ` Jon Forrest
2016-07-24 18:27         ` Jakub Narębski
2016-07-24 18:41           ` Jon Forrest [this message]
2016-07-25  7:04             ` Johannes Schindelin
2016-07-24 20:03           ` Jon Forrest
2016-07-26  9:15 ` Manlio Perillo
2016-07-26 14:22   ` Jon Forrest
2016-08-12 13:11 ` Sitaram Chamarty
2016-08-12 14:37   ` Jon Forrest
2016-08-13  0:30     ` Sitaram Chamarty

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=89e0a631-6396-e56e-0c1d-37acdbf8eda4@gmail.com \
    --to=nobozo@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=jnareb@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).