PR diffs, and git commits, are harder to read than they could be #2463
Comments
ansible-documentation-bot
bot
added
the
needs_triage
|
Yeah, you're right. That's quite irritating indeed. AFAIR, this is dictated by some weird i18n tooling that is external to this project. |
|
@kpinc Thanks for raising this. I'm a big fan of the "one sentence per line" convention, which is also referred to as semantic line breaks or ventilated prose. That convention has many benefits apart from making diffs more readable and improving the experience of reviewing docs. Dan Allen has a really good summary for asciidoc but the same points apply to RST and MD (although it can depend on where the markdown gets rendered). We've talked about this before and, as you suggest, enforcing the one sentence per line rule is difficult. But I totally agree that encouraging the use is a good thing and should be revisited. I've tagged this issue for discussion at the next DaWGs meeting. Feel free to join us on Matrix and let's talk about it. Here's the link to the next DaWGs meeting: https://forum.ansible.com/t/documentation-wg-weekly-meeting/7229 |
|
Also, just to point it out, the one sentence per line convention applies to the getting started content: https://github.com/ansible/ansible-documentation/tree/devel/docs/docsite/rst/getting_started |
oraNod
removed
the
needs_triage
|
@kpinc Thanks again for opening this issue, I've created a PR to add this to the style guide so we can start recommending the one sentence per line technique. Please feel free to take a look and add your thoughts or comments. |
|
BTW, there's also https://sembr.org/: Semantic Line Breaks That's even more fine-grained than "one line per sentence". (Edit: sorry, I only noticed now that it already got mentioned in the PR...) |
* issue #2463 one sentence per line style guide * Apply suggestions from code review --------- Co-authored-by: Sandra McCann <[email protected]>
github-project-automation
bot
moved this from 🆕 Triage
to ✅ Done
in Ansible Documentation
* issue #2463 one sentence per line style guide * Apply suggestions from code review --------- Co-authored-by: Sandra McCann <[email protected]> (cherry picked from commit 6aacf90)
* issue #2463 one sentence per line style guide * Apply suggestions from code review --------- Co-authored-by: Sandra McCann <[email protected]> (cherry picked from commit 6aacf90)
* issue #2463 one sentence per line style guide * Apply suggestions from code review --------- Co-authored-by: Sandra McCann <[email protected]> (cherry picked from commit 6aacf90)
* issue #2463 one sentence per line style guide * Apply suggestions from code review --------- (cherry picked from commit 6aacf90) Co-authored-by: Don Naro <[email protected]> Co-authored-by: Sandra McCann <[email protected]>
* issue #2463 one sentence per line style guide * Apply suggestions from code review --------- (cherry picked from commit 6aacf90) Co-authored-by: Don Naro <[email protected]> Co-authored-by: Sandra McCann <[email protected]>
* issue #2463 one sentence per line style guide * Apply suggestions from code review --------- (cherry picked from commit 6aacf90) Co-authored-by: Don Naro <[email protected]> Co-authored-by: Sandra McCann <[email protected]>
Hi,
I notice that the convention, in at least some files, is to line-break at the end of paragraphs. This makes diffs harder to read.
For example, look at the diff of PR #2416 at lines 245/248 (old/new). The change is that a new sentence was added to the end of the paragraph. But this is hard to see without close reading. If some comma was added somewhere in the middle of the paragraph it would be difficult to notice.
While this might be improved by a change to the git web interface, that does not help when using git itself, doing diffs while developing, etc.
So, I write this to suggest that the source code for the docs have line breaks after every sentence. I've seen this convention elsewhere, but can't recall where.
Enforcing this suggestion might be too much to ask, but it wouldn't hurt to consider adopting the practice and encouraging it's use.
Regards,
Karl
The text was updated successfully, but these errors were encountered: