Outreachy: Editor Guide internship updates

[thibaudcolas]

We’re now resuming work on guide.wagtail.org, as an Outreachy open source internship starting today. @activus-d is our new contributor, supported by @jonnypeaks, @Stormheg, @thibaudcolas, @allcaps, and Stephanie Brown.

Starting a new Discussions thread to share our occasional notes and updates – starting today, for the next 13 weeks. More context about this project is on Outreachy: Improve user guide documentation for Wagtail.

[thibaudcolas]

Sprint 1 planning session

• Keeping track of our backlog on https://github.com/orgs/wagtail/projects/21/views/1
• Planning our meeting schedule
• Reviewing Wagtail features relevant to document
• Considering new abilities for the site (to share a survey)

[activus-d]

Writing style guide

Writing style guides, referred to as "style guides" subsequently in this document, establish standards and outline the structure of written works. The standards help maintain consistency in grammar, voice, and tone. The use of a writing style guide also ensures that the content of the writing is clear, concise, and timeless.

Adoption of a style guide

It is a good idea to have a customized style guide when writing documents for smaller organizations. A customized style guide is also preferable if you are a lone writer. This way, you can have a voice and tone unique to you.

However, if several people will be reviewing your documents, it is best to follow a well-established style guide. This is also the case if someone other than you will be updating the documents in the future.

There are several well-established style guides, but the Microsoft Writing Style Guide and the Google developer documentation style guide are the most prominent. Both style guides have a lot in common. For instance, they both advocate for a voice and tone that is conversational, friendly, and respectful. Both style guides prefer writing from the perspective of the second person. Additionally, they prefer capitalizing the headings of documents in sentence case style.

Microsoft Writing Style Guide vs Google developer documentation

Microsoft Writing Style Guide	Google developer documentation style guide
Supports the use of en dashes instead of hyphens in describing ranges, dates, numbers, and compound modifiers.	Supports the use of hyphens instead of en dashes in describing ranges, dates, numbers, and compound modifiers.
Supports the use of slashes to separate alternative words (for example, country/region) and to describe fractions, dates, and equations.	Disapproves the use of slashes to separate alternative words and to describe fractions, dates, and equations.
Supports the use of curly quotation marks (“ ”) except in user input and code samples.	Supports the use of straight quotation marks (" ") at all times in the document.
Supports the use of sentence case capitalization generally but title style capitalization for names of products and services, names of blogs, book and song titles, article titles in citations, white paper titles, and the titles of people.	Supports the use of sentence case capitalization in all instances except when referencing the title of any work or source that doesn't follow the Google developer documentation style guide. In this case, you are to retain the original capitalization.

Personal preference

After examining the details of both style guides described earlier in this document, I prefer the Google developer documentation style guide for the following reasons:

• It is more detailed and provides more context. For instance, it gives reasons for discouraging the use of certain conventions.
• It provides examples of how to use the general rules and their exceptions, unlike the Microsoft Writing Style Guide, which doesn’t provide examples of how to use the rules.
• It sets a standard on how to document command-line syntax. There is no provision for this in the Microsft Writing Style Guide.
• It also sets a standard for writing timeless documentation.
• It has well-laid side navigation, and descriptive headings and subheadings. This makes it easy to skim through the style guide when searching for an applicable rule.

This document follows the Google developer documentation style guide.

[lb-]

Hey @activus-d - it's great that we are having this discussion.

I personally have no explicit preference for the actual guide we use but think we should pick one and go with it. If I needed to I would lean towards the Google one though.

One thing that can trip up people a lot is English US / UK spelling. We have made an explicit decision on the Development documentation to opt for UK (aka British) spelling. See https://docs.wagtail.org/en/stable/contributing/general_guidelines.html#language

I can see an argument for the guide using maybe US spelling but nonetheless I would hope it's consistent across the guide. My personal preference is to align with the development docs on this point though. If we don't clarify this - we will likely get constantly changing edits for updates to the 'correct' spelling back and forth for eternity haha.

For example - capitalisation (en-GB) vs capitalization (en-US).

Also. It's good to review that language section linked above as we have a note about Latin phrases and abbreviations. I think that both the Google and MS guides have something similar.

[activus-d]

@lb- It was unanimously agreed that the Google developer documentation style guide should be adopted. However, there is still no definite decision regarding whether American or British spelling should be used.

[lb-]

Awesome. Thanks for the update and thanks for the really succinct summary above presenting the options and reasoning.

No problems about the spelling choice, it may not need to be something that's intentionally decided at this point in time.

[activus-d]

@lb- Thanks for the compliment. As soon as any updates become available that you are not aware of, I will notify you here.

[zerolab]

Thank you for putting this together and for sharing at the core meeting earlier today 👏

[vossisboss]

I agree with your selection of the Google style guide. I generally find that one to be more straightforward and easier to understand than the Microsoft guide. I think you have made an excellent selection and agree that we should move forward with that choice.

[activus-d]

@vossisboss I will do just that. Thank you for your timely feedback.