On Mon, Jan 22, 2018 at 8:51 AM Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> org-edit-src-content-indentation: ?

It is 2. I'd favor 0, but I don't care much.

I also favor 0, less white space noise, the better.
 
> This is necessary so that contributors don't mess up accidentally with
> the desired format.

Why does it matter? We just put them in ".dir-locals.el" and be done
with it. They override user's preferences anyway.

+1
 
> Also, why are :PROPERTIES: drawers at the beginning of the line?

I set `org-adapt-indentation' to nil in the file above. It gives more
columns in a line, which I find more comfortable (e.g., text always
starts at the same column).

Another place where we can prevent unnecessary white space.

I have always started PROPERTIES at col 0. With org-indent-mode enabled, it doesn't matter.. looks pretty (PROPERTY drawer in below screenshot actually starts at col 0):

image.png
 
  - use example blocks for Org syntax instead of "begin_src org",

I'd prefer "begin_src org". When these manuals are converted to HTML, we can use syntax highlighting to format comments, etc in Org snippets. I think it's good to retain the meta data that that is not an arbitrary block of text, but Org data. Can you please revert to "begin_src org"?
 
  - internal links to headlines always start with a star,

Nice.

  - tags, node properties, are not shown with the surrounding columns,
  - when to use =...= or ~...~ markup:
    - files or extensions use =...=,
    - anything that is meant to be written in the Org buffer uses =...=,
    - any meaningful token in a programming language uses ~...~.

Sounds good.


--

Kaushal Modi