Philip Durbin π (Dec 13 2025 at 15:23): Philip Durbin π (Dec 13 2025 at 15:23):"Please please very much please use one sentence per line. It makes typing (and reading) suggestions so much easier. Thanks." -- https://github.com/IQSS/dataverse/pull/12041#pullrequestreview-3571376646
Philip Durbin π (Dec 13 2025 at 15:24):@Oliver Bertuch I'd love to understand this request better because you seem pretty animated about it. :smile:
Philip Durbin π (Dec 13 2025 at 15:24):When writing, I don't put every sentence on its own line.
Philip Durbin π (Dec 13 2025 at 15:25):That would be weird. Unnatural.
Philip Durbin π (Dec 13 2025 at 15:25):However, the context above is release notes. Markdown format. I can sort of understand where you're coming from.
Philip Durbin π (Dec 13 2025 at 15:29):Like Markdown, reStructuredText also allows you to write one sentence per line in the source format because it strips out the newlines to construct a proper paragraph without newlines.
Philip Durbin π (Dec 13 2025 at 15:29):So I'm wondering if your desire to write one sentence per line applies to all .md and .rst files.
Oliver Bertuch (Dec 13 2025 at 15:38):When writing docs, I see and try to treat them the same way we write code. You don't put all the lines of a method on one line, right? Inline docs for code very much benefit from trying to keep a sentence as long as a line is, fostering concise wording.
Oliver Bertuch (Dec 13 2025 at 15:38):But aside from that, it's just so much easier with anything related to version control!
Oliver Bertuch (Dec 13 2025 at 15:39):When making a suggestion and a whole paragraph is on one line, you need to copy paste it all in there to have the diff done.
Oliver Bertuch (Dec 13 2025 at 15:40):When trying to look for changes by diffing the docs, having all sentences of a paragraph on a single line, it's just making it all a lot harder.
Oliver Bertuch (Dec 13 2025 at 15:41):And it's not just me... Here's some input:
Oliver Bertuch (Dec 13 2025 at 15:43):Whenever I write any docs/pages in MD, RST, HTML or whatever, I'm sticking to this pattern. Running an analysis in our guide's pages by committer would probably quickly reveal this habit... :nerd:
Oliver Bertuch (Dec 13 2025 at 15:44):This goes as far as me ranting about the JavaDocs parser not respecting line breaks, forcing me to put <p> tags manually when it coulf just have been a double line break. (Also I heard there's some MD preprocessor for Javadocs)
Oliver Bertuch (Dec 13 2025 at 15:47):Philip Durbin π said:
Oliver Bertuch I'd love to understand this request better because you seem pretty animated about it. :smile:
Yeah it was a lot more work to make the suggestions by having to copy and paste these very long lines... And its not the first time I split up paragraphs in the docs, as most of our devs have this habit of making these gargantuan lines.
Philip Durbin π (Dec 13 2025 at 16:19):I think I need to sleep on it. Ponder more. It's a big change. Unnatural, like I said, when writing prose.
Philip Durbin π (Dec 13 2025 at 16:27):I don't love how https://raw.githubusercontent.com/asciidoctor/asciidoctor.org/main/docs/asciidoc-recommended-practices.adoc looks. The source of that page.
Philip Durbin π (Dec 13 2025 at 16:30):I like how this looks, for example:
These meetups are extremely casual. Often [we](https://bostonopen.github.io/people) are around 5-7 people. We eat. We chat. We talk about open source. We talk about all kinds of things. Whether you're an experienced open source developer or user, or you're just curious about open source, you're welcome to join!
I like one line instead of seven. Much more readable in its raw form.
Oliver Bertuch (Dec 13 2025 at 16:56):That's why I most often use raw and rendered view side-by-side in the IDE. Also, making sentences more or less equally long helps with keeping a block like nature in the raw editor.
Philip Durbin π (Dec 14 2025 at 04:03):Making sentences equally long rubs me the wrong way. Let them be free to be as long or as short as they need to be! :smile:
Vaida PlankytΔ π¨ (Jan 06 2026 at 10:23):varying the length of sentences is great for maintaining focus/interest when reading! you can never expect what the author will hit you with next. a statement. or a long, sprawling description :performing_arts:
Last updated: Jan 09 2026 at 14:18 UTC