Add a style guide for contributions

[sebbASF]

It might be useful to provide a style guide for contributions.

This could cover:

• info on metadata (how are they used; no blank lines!)
• when to use plain links and when to use target=_blank
• don't use 'here' for link text
• each sentence on a single line
• referencing ASF data

[bproffitt]

I agree (except for the each sentence on a single line bit, that's a hard no :) ), but this dups #231 a bit. I'm thinking a style guide for that issue will solve the problems that you and @ShaneCurcuru are trying to solve. So, I am going to close this issue, and can we move commentary/discussion to #231 please?

[sebbASF]

I do not understand why you are against recommending starting each sentence on a new line in new content. It does not affect the rendered output, but makes it much easier to review changes. What harm does it do?

[craigmcc]

Brian, I have no skin in the game on this particular issue, but after a 40 year career in software development, I'd appreciate it if you appreciated the viewpoint of those of us who do code reviews (which of course includes commit reviews) for a living.

Just as an extremely trivial example, let's say I have defined a Javascript object like this:

const example = {
  foo: "bar",
  baz: "bop"
}

Now, let's say I (as a developer) needs to change that to:

const example = {
  foo: "bar",
  baz: "bop",
  something: "else"
}

What does a code reviewer see? A two line change (adding the stupid "," at the end of the baz line, plus the new one). Two line changes means the reviewer has to look at both lines to see if anything else (besides the newly trailing ",") was changed on the first line.

In the particular case of Javascript, I could have said this in the original code:

const example = {
  foo: "bar",
  baz: "bop",
}

Note the extra "," after the second element. Does it make ANY semantic difference whether that comma was there originally or not? Nope, because Javascript doesn't care. Does that matter to a code reviewer? ABSOLUTELY. One less thing to have to go back and review, because it would show up as a ONE line change

How does this affect the discussion here? HTML based environments wrap text when they need to, regardless of the multiple lines (or not) in the original source.

This may or may not matter as much on edits to website text. I have no particular opinion on that, as I'm not in that world at all. But it DOES matter to the people who basically ARE the ASF -- so please back off on the absolutist positions you have been articulating, given that lots of us DO care about such things.

[sebbASF]

See also https://github.com/apache/www-site/issues/224#issuecomment-1643508333 which points out that concatenated lines are incompatible with the way git is designed to handle merges.

[bproffitt]

We're not discussing code; we're discussing text/content, which is organized linguistically in a much different way. One sentence per line would make it difficult to make sure content was organized properly. I have worked on websites that maintained such a policy and I can tell you from experience it is not easy. even with word wrapping. One missing blank line and now you have two paragraphs jammed together that should not be.

I am struck by this argument of absolutism. Are we not all knowledgeable in the fields we are volunteering in? You said it yourself:

"This may or may not matter as much on edits to website text. I have no particular opinion on that, as I'm not in that world at all. "

If you are talking about code on the site, then of course it's one line per line of code, but onesentence per line implies text to me, not code, and I am answering that request with a "no." I am in this world, and as maintainer of the site, I don't think it's absolutist at all to say, "I don't think this is a good idea." Don't project maintainers have the right to not approve new code for their software?

Now, I closed this because it dups #231 I am closing this again and will copy this reply to #231 because that's where the discussion should be. I would think that someone in your world would appreciate the value of issue management.