Re: RFC - Git Developer Blog

From: Emily Shaffer <emilyshaffer@google.com>
Date: Aug 6, 2019, 20:49 UTC
Message-ID: <20190806204925.GA196191@google.com>
In-Reply-To: <20190806132052.GB18442@sigill.intra.peff.net>

On Tue, Aug 06, 2019 at 09:20:52AM -0400, Jeff King wrote:

Show 9 quoted lines

> On Mon, Aug 05, 2019 at 06:49:35PM -0700, Emily Shaffer wrote:
> 
> > Are folks interested in writing and reviewing this kind of content? Any
> > ideas for where we may be able to host (maybe git-scm)?
> 
> I think it would make sense to have blog.git-scm.com (and .org) with
> this content. I'd be happy to deal with the technical side of setting
> the name up. I think it should live in a different repository than the
> main site, though (which is an overly-messy Rails app).

I'd certainly be happy with that setup if others agree, although the incorporation with Git Rev News sounds interesting too (I'll reply to that post also).

Show 21 quoted lines

> 
> There actually used to be a blog section on the site. It discussed
> various high-level concepts that hadn't made it into the Pro Git book
> (whose content makes up most of the site). But as most of those were
> eventually added to the book, the blog posts became staler versions of
> the same content, and we dropped them.
> 
> Just to play devil's advocate for a moment: another venue for topics
> like these:
> 
> >  - Using `git worktree` Effectively
> >  - Overview of the Git Object Store
> >  - Finding Regressions with `git bisect`
> >  - Life of a Git Remote Request
> 
> might be to actually add them to the book (which started as a
> single-author publication, but is CC-licensed and has taken lots of
> community content over the years). The advantage there is that the book
> content would always represent the most up-to-date coverage of those
> topics, whereas blog posts sometimes grow stale over the years as nobody
> is interested in updating them.

To advocate your advocate, does the book content really stay so up-to-date? (I have no experience with that repo, so I really don't know.) An advantage of blog posts is that they come with a date and so users can judge for themselves how stale it is or is not. In fact I think it'd be odd to see reviews to update a blog post that's a few years old; if the content is so different I'd expect to see a brand new post and an editor's note on the top of the old one pointing forward, or at least marking it as obsolete.

If it's a concept that's so specific that it really will stale out quickly (e.g. exactly how to use git worktree down to the commands without much context) vs. a higher level concept (how does git worktree work and conceptually how do you use it) then it probably does belong in the manpage or book. But I suppose I envision these types of posts doing the latter, instead. Hmmmmm.

Maybe it's enough to say during review, "This seems like a good candidate to move to manual/tutorial/git-scm book".

Show 36 quoted lines

> 
> One downside is that it may be more annoying to try to integrate content
> into the existing structure of the book. Another is that a blog is
> something people subscribe to, so a post may generate attention/interest
> in a topic (but nobody wants to see a feed of book updates!). A prime
> example is something like a highlight of features after a new release,
> which is not book content at all, and just serves to generate attention.
> :)
> 
> So I don't think I'm really seriously suggesting this as an alternative,
> but maybe something to ponder.
> 
> > It could make sense to review contributions like this on the mailing
> > list, so that we get the attention of those who wrote the features
> > that are being covered in the blog posts - are we okay with the
> > additional traffic?
> 
> Additional traffic is fine. I do suspect that blog posts in particular
> would benefit from a more integrated review system like GitHub (or
> similar):
> 
>   - I'd expect there to be a lot of images, and those systems make
>     image diffs easy to see
> 
>   - the formatted output is going to be important to review; a
>     browser-based review system makes it easier to see the formatted
>     output (especially if they're written in markdown)
> 
>   - we're more likely to get/want drive-by fixes like typo corrections,
>     so reducing friction for non-regular contributors is more important
> 
> Obviously you can apply many of the same mailing list vs web review
> arguments that we've already had for writing Git itself (e.g., is
> reviewing formatted output much different than looking at the output of
> a compiled program?). But I think the nature of blog posts pushes it a
> bit further towards web-based review.

I follow, especially re formatted output and images, but I also don't want to provide too much distance between the ML and these kinds of posts. I wonder if it makes sense to mandate use of GitGitGadget, and accept review comments both on the ML and the PR?

> 
> -Peff