Technical issues

[erget]

This issue is for discussion, potentially at the upcoming CF Community Meeting, on how to take care of the source codes for the Conventions, and taking care of some technical debt therein.

All of the suggestions below are my own and some people may disagree with them, I'm just collecting for now.

1. We have a lot of broken links and could fix them.
2. It would be a good idea to use aliases for hyperlinks rather than embedding the URLs in the text, so that it's easier to move the links if needed.
3. Putting single sentences on a line of their own would improve readability of diffs and help us track changes better - restricting lines by character length isn't really necessary for a document of this type.
4. Eliminating trailing whitespace would also be good.

In terms of helping issues move along our pipeline, a few ideas:

1. Use project boards
2. Eliminate the "question" template, instead directing users to the "discuss" repo
3. Adding checks to the PR template - are authors included in author list? Is the change recorded in the changelog, so that we don't have to do archaeology at the end before a release?
4. Ask contributors to mark WIP PRs as such

[ethanrd]

@erget - A comment, before I forget, on the single sentence per line item above.

I agree a single sentence is better than line length or just stringing it all together.

Another option to consider is "Semantic Line Breaks" which are described in this "Semantic Linefeeds" article by Brandon Rhodes. Which includes a quote from “Hints for Preparing Documents” by B.W. Kernighan in 1974:

Most documents go through several versions (always more than you expected) before they are finally finished. Accordingly, you should do whatever possible to make the job of changing them easy.

First, when you do the purely mechanical operations of typing, type so subsequent editing will be easy. Start each sentence on a new line. Make lines short, and break lines at natural places, such as after commas and semicolons, rather than randomly. Since most people change documents by rewriting phrases and adding, deleting and rearranging sentences, these precautions simplify any editing you have to do later.

[larsbarring]

What is the status of these suggested changes? To me it looks like some have been fixed:

1. We have a lot of broken links and could fix them. ---- Done ?
2. It would be a good idea to use aliases for hyperlinks rather than embedding the URLs in the text, so that it's easier to move the links if needed. ---- Not yet ?
3. Putting single sentences on a line of their own would improve readability of diffs and help us track changes better - restricting lines by character length isn't really necessary for a document of this type. ---- Done ?
4. Eliminating trailing whitespace would also be good. ---- Done ?

[ChrisBarker-NOAA]

Just a couple one notes -- these are all great ideas.

1. "Putting single sentences on a line of their own" -- I think long lines can still be an issue, I like the "semantic line breaks" option -- break on sentences, but also semi-colons, commas', etc, when the line gets long. What bad, in a git-managed document is very long lines -- e.g. one paragraph as a singie line, because the diffs are done line-by-line.

Do we have these rules written down anywhere?

2. In any case, it's probably better to not make changes that are only re-formatting, that makes understanding the history harder. If it's not already been done, I think it's better to reformat a paragraph only when it's being edited for some other reason.

[erget]

Ho ho ho, thanks for reviving this zombie! I'm going to close this issue because as @larsbarring notes most of these are basically done. @ChrisBarker-NOAA I also agree with your stance - IIRC we agreed on the "semantic line breaks" as a rule of thumb. In terms of written down guidelines, we now have https://github.com/cf-convention/cf-conventions/blob/main/CONTRIBUTING.md and that references https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line. I wouldn't apply that so strictly as to do something like for f in *; do sed 's/\([.!?]\)/\1\n/g' $f; done but rather take that as a guide and try to work from there.

If there's interest, addressing the aliases for links could be a new issue - I might pursue that when I get a free moment myself, but won't open the ticket until I plan on actually doing something about it :)