Re: Announcing 3 git docs: Best Practices, fixing mistakes, post-production editing

Seth Robertson [off-list ref] writes:

In message [ref], Junio C Hamano writes:
    Just a few I noticed that are dubious to be in a document that is meant to
    describe "best practices".
...
    "Don't panic"
    -------------

    * As we never "auto-stash", anything that is on stash is by definition
      what the user deliberately placed, just like a commit on a branch that
      the user may have forgotten.  So it is strange to count it as one of the
      three places that "lost" commit may be hiding.  If you make it four and
      add "a branch you might have forgotten" to the mix, it would make a bit
      more sense, though.

I do.

You don't.  You say "There are THREE places where "last" changes can be
hiding" and list these three things, not four.

    "Do keep up to date"
    --------------------

    * You explained in "Do choose a workflow" section that different workflows
      suite different projects.  ... it
      would be more useful to say in what workflow and the workflow elements
      such as "pull --rebase" you advocate in this section are suited (you do
      not have to say in what other workflow they are inappropriate).

In the pull --rebase section, I spend one short paragraph talking
about why I think it is a good idea and four providing arguments
against it.  In my opinion,...

I do not know if you have updated the version seen on the web since the
review comments, but I was merely suggesting that "what I recommend here
may not be desirable for some workflows" without spelling out what these
workflows are would be less helpful to readers than being more explicit,
i.e. "these suggestions are good for this and that workflows".

This section by nature of what is discussed is bound to be incomplete and
will not be "universal truth" as there does no "universal truth" exist.
Letting the users know that for what kind of workflows these are good
suggestions upfront will help them to decide if the recommendations are
applicalble to them.