Provide style guide and minimal output template for other sites

[ShaneCurcuru]

Once the nav redesign is implemented, we need a developer's guide to the minimal styling/output template needed so that a handful of othersite.apache.org domains can use to update their styling to mirror or match the main a.o site.

For example, some Whimsy pages provide custom categorized/organized content about board meeting minutes, which are useful for the general public:

https://whimsy.apache.org/board/minutes/

Since that page has a useful structured & automated output of data that's focused on the general public, the Whimsy PMC would like to match or even just "mostly mirror" the main a.o site's style, without needing to directly be part of the main site's build system. There are likely other similar sites that would like to do the same things.

[sebbASF]

I don't think Whimsy is a good example:

Whimsy gets the layout from parsing the page https://www.apache.org/foundation/board/calendar.html.
This is not something that would be advisable in general.

Note also that any templates are likely to be dependent on the build system, in this case Pelican

[sebbASF]

Ideas for style guide copied unchanged from #256:

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]

To continue from a dup issue:

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 one_sentence_ 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 closed it 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.

[sebbASF]

Are you saying that a single paragraph should always be on a single line? That will result in some extremely long lines.

Or that paragraphs can be wrapped,
but should only be wrapped
mid-sentence, and never at the end of a
sentence? That would allow
for shorter lines.

[clr-apache]

Peanut gallery: I edit code and text and I've found the best and most efficient text edit/review is if text is short lines and no more than one sentence per line break. Short lines is much less important than one sentence per break. Craig

On Jul 26, 2023, at 05:15, Brian Proffitt ***@***.***> wrote: To continue from a dup issue: 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 one_sentence_ 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 <#231> I closed it again and will copy this reply to #231 <#231> because that's where the discussion should be. I would think that someone in your world would appreciate the value of issue management. — Reply to this email directly, view it on GitHub <#231 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AD4M6RFXMSPOT3RKM4OOWI3XSEC73ANCNFSM6AAAAAAZRX7BJU>. You are receiving this because you are subscribed to this thread.

Craig L Russell ***@***.***

[bproffitt]

I'm saying that any lengthy bit of text like a paragraph can be edited by turning on "Soft Wrap" in GitHub or "Word Wrap" functionality in any third-party text editor.

[desruisseaux]

I'm saying that any lengthy bit of text like a paragraph can be edited by turning on "Soft Wrap" in GitHub or "Word Wrap" functionality in any third-party text editor.

But the text committed on the Git or SVN repository would still be a single long line for a whole paragraph?

I have experience in editing standards and engineering reports from the Open Geospatial Consortium organisation, which uses Metanorma (a kind of AsciiDoc). A lot of them where written with one line per paragraph. When I have to touch such an existing document, the first thing that I do is to a send a big merge request where I break all paragraphs at least in the sections that I plan to edit, with the promise that I didn't changed anything except breaking lines. Only after that I can send other merge requests making some changes in the texts, in a way that can be reviewed more easily, commented more accurately (with comments on specific lines), and merged with less risk of conflicts.

The "each sentence on a single line" rule does not need to be absolute, but is a guideline. If the sentence is very long, it may need to be broken on two lines. If two consecutive sentences are very short and are closely related, it may be okay to keep them on the same line. But the recommendation to break paragraphs is not only for editing. It is also for reviewing, merging and Git/SVN history. Tools like diff viewers or word wrap hide the problem of large diffs instead of resolving the problem.

[sebbASF]

I'm saying that any lengthy bit of text like a paragraph can be edited by turning on "Soft Wrap" in GitHub or "Word Wrap" functionality in any third-party text editor.

How do you enable soft wrap for the quote in this issue? #258

[sebbASF]

Another problem with long lines is that they may be truncated in commit messages.
See for example: https://lists.apache.org/thread/l5ffzv1k1pc78rdj1ptdqy8r7t2rcfgh (requires login)

Also the associated PR (#260) is not at all easy to review.

[bproffitt]

That's unfortunate that content is truncated in the commit messages, but all reviews should be done in GitHub anyway, so this is a non-issue. #260 is a long paragraph, but I was easily able to find the new addition about GSoC, approve it, and merge it.

[sebbASF]

Note that the patch included changes other than adding GSoC.
There were some half-dozen changes in all.