Update Style Guide

[gardners]

The style guide is currently silent on a couple of key points:

1. Active vs passive voice: My gut feeling is it should be "active voice" so that it feels more personal, and like some of the good guides of the 1980s.
2. Level of formality: Again, my gut feeling is it should be "on the border between formal and informal", favouring "relaxed prose, tending to semi-conversational where appropriate, but never waffling".

Then the existing text probably needs checking against these decisions.

[cheveron]

1. Today, as a general rule active voice is preferred. But there are times when passive voice is appropriate. The rule I use is that if having rewritten it in active voice it doesn’t scan as well, leave it in passive.2. A 1980s manual wouldn’t use contractions.Taking a look at my Atari Mega ST manual from the late 80s, it’s all passive voice. But it does address the reader directly (as you).Sent from my iPadOn 30 Dec 2022, at 21:39, Paul Gardner-Stephen @.***> wrote: The style guide is currently silent on a couple of key points:

Active vs passive voice: My gut feeling is it should be "active voice" so that it feels more personal, and like some of the good guides of the 1980s. Level of formality: Again, my gut feeling is it should be "on the border between formal and informal", favouring "relaxed prose, tending to semi-conversational where appropriate, but never waffling".

Then the existing text probably needs checking against these decisions.

—Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you are subscribed to this thread.Message ID: @.***>

[dansanderson]

Most modern style guides recommend the active voice to combat excessive use of the passive voice, and ours can follow suit. (I'm surprised if it doesn't already.) It's especially worth emphasizing in technical writing because it isn't always natural to ascribe action to inanimate objects or understand what the action is. That doesn't mean every sentence should use the active voice: I've written about way too many APIs "providing" functionality in my day.

Re: formality, this could be more specific. Informality (including anthropomorphism and active voice) makes more sense in an introduction or tutorial, formality (including passive voice) is more important in reference. I think some of the style inconsistency we see from contributions is due to writers not taking the structure of the entire book into account. We have some information we want to add to the pile, so we look for where related topics are discussed, then add an "explanation" in that location without further consideration. Most of the Compendium consists of reference appendices at the moment; we want to add tutorial-style writing to the book but it isn't clear where it should go.

It would help to rework the overall table of contents and seed empty sections with topics (even incomplete drafts) so people know where to put contributions, and what style is appropriate for that section.

[dansanderson]

MSSG on active vs. passive (with a trite recommendation of "Keep it active whenever you can"): https://learn.microsoft.com/en-us/style-guide/grammar/verbs

[nobruinfo]

@dansanderson I'm a bit unhappy @gardners wrote this ticket. I just wanted to pinpoint the topic because it is one aspect of my both PRs I felt a bit delayed with. And especially stealing valuable time from you and Gurce. But let's simply forget that.

I think, the ticket here has no priority. There are many other tickets wanting to fix things in the manuals. Thus I initially stepped in. Looking back to the work this cost I now think to better leave this up to you all. Don't worry, I'll find different things to do with Xemu. The Mega65 is way too intersting to be stuck in phrasing and wording.

Many thanks to all of you for an excellent documentation we have as the manuals, on the file host, in Confluence and of course in yours and blogs of all the others. Could I have a glance to the obviously existing "style guide" ?

[dansanderson]

@nobruinfo I hope that you won't be deterred to contribute. Your contributions identified a need and installed a solution, and they improved the manual. The subsequent revisions of the solution also improved the manual. Together we took two steps forward. With the currently defined scope of the manual, there are many sections remaining to be drafted, and we need to be more accepting both of first drafts and of the reality that first drafts will be revised. Writing is rewrtiing.

I think we can reduce the strain of the drafting process by doing less rewriting in the PR review process, and trust that subsequent PRs will improve things. I can understand if you'd prefer not to engage with the task of drafting, but I hope you will at least continue to file Issues as you identify needs in the manual. If you'd like to contribute a diagram without the surrounding text, you can attach the diagram to the Issue. IMO, with the current state of the manual, you could even add the diagram to the book with a "TODO" in the text. (We should implement a standard way to do this.)

The MEGA65 book style guide cites the BBC News Style Guide and the Microsoft Style Guide as bases.

[nobruinfo]

@dansanderson Ouch, I seem to simply have overlooked there actually is a style guide within the same repo. Will stick to it, of course.

I think I now also understand another misconception of mine. It is up to the contributors to file issue tickets, not to resolve them. I'll therefore also go from that.

[dansanderson]

Everyone is welcome to submit pull requests.

PRs undergo a review process. We can and should do better to make the review process easier, hence my suggestion to be more lenient about writing style issues for most PRs. Only people hoping to become core contributors need to fully indoctrinate themselves with the scope, organization, and style of the project, and work closely with other core contributors on multiple revisions. That shouldn't be everyone's job, and we miss out on important contributions if we hold the bar too high.

The only other thing I'd mention is that anyone submitting a PR may need to be patient when the core team can't get to a PR right away. We all have limited resources. And we should all get comfortable with the idea that our writing may be rewritten in a future change—just like with software contributions.

[nobruinfo]

@dansanderson Maybe I also was slightly misunderstood. I was not unhappy about to wait for PRs to be treated. I was only surprised by the level of detail all came back to me while always saying to have to little time to. Let us this all put aside - for me waiting for something never was a problem.

There is one little caveat along Github with pull requests. As long there is one open waiting all following pushes within my fork are automatically assigned to the very first one. Either the maintainer gets confused or the contributor stops pushing different stuff. That is my current position, also no problem.

The core team needs to stay small, no question about that. But also it should be able to not only hunt down new features but also to not cut off newcomers. That's why I began to work on some smaller parts of the manuals, after I had struggled to suggest wiki improvements for the repo of Xemu. Let's see how things are going to develop.

[lydon42]

You just need to make a branch for each of your PRs to separate them from each other. As long as the stuff you are doing thematically fits, then this is not needed and I don't think we will get confused. But when doing stuff on different chapters that are unrelated, then separating by branch is a good idea.

[nobruinfo]

@lydon42 Thank you for this tip. I'll give it a try.

[dansanderson]

I'm resolving this ticket. The cited style issues are described in the project style guide, and the style guide has had some love recently. Feel free to file tickets about specific style concerns not already covered in styleguide.pdf.