[docs] Add writing style guide #4271

mattstein · 2022-10-07T16:47:54Z

The Problem/Issue/Bug:

While there are tools in place for linting and spell-checking the documentation, there aren’t any higher-level guidelines that clarify how it should be written. Without a clear standard, the organization and flow of the documentation is limited to the efforts and perspectives of individual contributors.

How this PR Solves The Problem:

This PR renames the “Styleguide” page to “Brand Guide”—which should be a more specific and appropriate description of that content—and adds a “Writing Style Guide” to comprehensively detail objectives from #4200 with some additional considerations for the broader effort of #4188 and a reference to the related aims of the Code of Conduct.

It adds some initial examples that could probably be improved or grown to clearly illustrate various recommendations.

This writing guide is not meant to be overbearing required reading for contributors, but an evolving document that can capture whatever goals and conventions we aspire to, with the ultimate purpose of encouraging the docs toward consistency.

Manual Testing Instructions:

https://ddev.readthedocs.io/en/latest/developers/testing-docs/

Related Issue Link(s):

mattstein · 2022-10-07T16:50:40Z

@rfay There’s some opinionated stuff in here, but the next step for #4188 and worth nailing down regardless of what needs discussion or revision! Eager to see what you think.

rfay

This is great. The only potential problems are:

It could inhibit contribution if people discover it and think that they have to do everything in it.
Maintenance could be a long-term commitment by the incredible author of this PR :)

rfay · 2022-10-07T17:14:00Z

mkdocs.yml

@@ -165,5 +165,6 @@ nav:
      - developers/github-selfhosted-setup.md
      - developers/project-types.md
      - developers/release-management.md
-      - developers/styleguide.md


We'll want to add a redirect for this after it goes in.

Is that something I can do here?

Not AFAIK. I've been doing redirects in readthedocs. And of course this might break stable while latest is out there. I don't think it's all that important, but let's remember we have a task after it's pulled.

rfay · 2022-10-07T17:16:11Z

docs/content/developers/writing-style-guide.md

+
+| Write This 👍 | Not This ❌
+| -- | --
+| Run `ddev start` and launch the site in a browser. | Please run `ddev start`, then launch the site in a browser.


Suggested change

| Run `ddev start` and launch the site in a browser. | Please run `ddev start`, then launch the site in a browser.

| Run `ddev start` and launch the site in a browser. | Please run `ddev start`, then use `ddev launch` to view the site in a browser.

This may be an awful example to start with—added ddev launch to the ideal example as well, since your suggested improvement only made the “Not This” example more useful.

Suggested change

| Run `ddev start` and launch the site in a browser. | Please run `ddev start`, then launch the site in a browser.

| Run `ddev start`, then run `ddev launch` to open the site in a browser. | Please run `ddev start`, then use `ddev launch` to view the site in a browser.

This example is really just illustrating how not to start a sentence with “Please”, which is probably insulting to anyone with a pulse. Might be better to get rid of it or come up with another one.

Your choice here. It's hard to review these tables in a PR, so gets confusing.

I’ll come back to this and try for a new example. In the meantime, I added a screenshot to the PR description since the illustrations (via table and !!!tip examples) are a big part of it.

@rfay

Clicking on this button will give you a more Visual view of the PR.

rfay · 2022-10-07T17:20:02Z

docs/content/developers/writing-style-guide.md

+
+### Write Once and Link
+
+Try to keep from repeating yourself in the documentation. Instead, write carefully and link to that well-crafted specimen, whether it’s across the page or off to another section. This has two benefits:


Absolutely correct, but there are times that links with necessary info distract from the flow, so it's better to just tell them the missing info.

The realist in me probably agrees, but I have lists of redundancies to go through and address—both linking to canonical explanation and adding the ability to link it in the first place. (Like individual commands that live in a table, for example.)

rfay · 2022-10-07T17:23:32Z

docs/content/developers/writing-style-guide.md

+
+| Write This 👍 | Not This ❌ |
+| -- | -- |
+| web server | webserver


I like webserver better :)

You’re clearly not alone! Same issue in this ancient battleground.

I can live with styles I don't naturally do.

mattstein · 2022-10-07T17:48:21Z

It could inhibit contribution if people discover it and think that they have to do everything in it.

I’m not sure how to get around that, unless it’s something to clarify more urgently at the top of the new page. I added it as the last page in that section on purpose, and would not link to it from a PR template or anything that might suggest it’s required.

The alternative is not clarifying any shared standard, which leaves consistency and common form to chance or the most opinionated and diligent contributor(s).

If there’s a better way to strike the right balance, I’d love to know! If ddev.com changes shape, this could move there instead along with the brand guide and maybe a revamped FAQ—all with possibly more broad material that doesn’t need to live with the project source.

Maintenance could be a long-term commitment by the incredible author of this PR :)

Flattery aside, the aim of this document is precisely the opposite: for that author to expose his assumptions for scrutiny, so it’s the best of our consensus and not the work of some rogue pedant.

Helping to gracefully maintain that uniformity is a necessary task, especially while this effort is young, but IMO it should be guided by clear aims that are equally clear and accessible to everyone.

rfay · 2022-10-07T17:53:21Z

rogue pedant

😸

The reality is that without someone opinionated and tuned in, none of this will actually have any effect, so I stand by my statement.

And the value of this guide is that it states our aspirations, so on its own can have significant value.

I confess that one thing I love about writing golang code is that there are absolutely no discussions about tabs or spaces or anything else. There's one way to do it, and gofmt enforces that. It's so great! We won't be able to get that about English, but a statement of intent like this at least goes a ways toward it.

mattstein · 2022-10-07T17:58:56Z

I confess that one thing I love about writing golang code is that there are absolutely no discussions about tabs or spaces or anything else. There's one way to do it, and gofmt enforces that. It's so great! We won't be able to get that about English, but a statement of intent like this at least goes a ways toward it.

Me too! Same with using a common Prettier setup with Vue or React—I spend more time thinking about my code than how it’s formatted.

English is a more subjective and sometimes horrible soup, but it sounds like we’re agreeing on the value of the document and I’m probably underestimating the effort required to adhere to it. As long as the statement itself isn’t turning people away, I’m happy to try and help encourage its adoption.

mayankguptadotcom

Reviewed. Other than 1 spelling mistake everything looks good.

docs/content/developers/writing-style-guide.md

Co-authored-by: Mayank Gupta <mayank@mayankgupta.com>

rfay · 2022-10-07T22:54:28Z

BTW, I don't think you need to do a screenshot, since the link to the readthedocs build is adequate, for example https://ddev--4271.org.readthedocs.build/en/4271/developers/writing-style-guide/

mayankguptadotcom

This looks good to me.
Thanks @mattstein

mayankguptadotcom · 2022-10-07T22:59:41Z

This looks good to me. Thanks @mattstein

It's strange. It said that it passed all checks and now it says it's failing 1.

mattstein · 2022-10-07T23:19:49Z

It's strange. It said that it passed all checks and now it says it's failing 1.

Ah, the failure actually makes sense because I need to bypass checks for incorrect examples on this page. Will see if I can figure that out.

rfay · 2022-10-07T23:54:01Z

Just took a look, haven't found an inline way to disable spellcheck. But things inside codeblocks are ignored... There are at least 3 components at play here:

mattstein · 2022-10-07T23:58:31Z

Thanks! I’m messing with .spellcheck.yml trying to use a CSS selector in that html pipeline that’ll ignore the offending word:

<span class="spellcheck-ignore">addon</span>

  - pyspelling.filters.html:
      comments: false
      ignores:
      - code
      - pre
      - span.spellcheck-ignore

It doesn’t have any effect when I run make pyspelling though, so I may need to spend more time to actually understand what’s going on.

rfay · 2022-10-08T00:11:46Z

The maintainer of pyspelling, facelessuser, is super helpful and responsive...

mattstein · 2022-10-08T01:22:20Z

Turns out it was an instance of “addon” that needed fixing elsewhere. I didn’t realize the entire developer section was already excluded from spell-checking.

rfay · 2022-10-08T03:48:12Z

Current failure is just that plugins.jetbrains.com is down

docs/content/developers/writing-style-guide.md

rfay · 2022-10-08T15:09:45Z

I added the redirect for developers/styleguide -> developers/brand-guide

mattstein added 3 commits October 7, 2022 08:41

Add initial writing style guide, re-title brand guide. [skip ci]

4b0d137

Reference Code of Conduct. [skip ci]

e0d2a22

Reference Writing Style Guide. [skip ci]

1c233a9

mattstein self-assigned this Oct 7, 2022

mattstein marked this pull request as ready for review October 7, 2022 16:48

mattstein requested a review from rfay October 7, 2022 16:49

rfay reviewed Oct 7, 2022

View reviewed changes

rfay requested a review from mayankguptadotcom October 7, 2022 17:35

mayankguptadotcom suggested changes Oct 7, 2022

View reviewed changes

docs/content/developers/writing-style-guide.md Outdated Show resolved Hide resolved

Fix spellcheck typo on imaginable

0c2d23f

Co-authored-by: Mayank Gupta <mayank@mayankgupta.com>

mayankguptadotcom approved these changes Oct 7, 2022

View reviewed changes

Fix spelling error.

5b2f277

rfay reviewed Oct 8, 2022

View reviewed changes

docs/content/developers/writing-style-guide.md Outdated Show resolved Hide resolved

Fix broken demonstration link

cbced4b

rfay merged commit 8527dc7 into ddev:master Oct 8, 2022

mattstein deleted the docs/writing-style-guide branch October 10, 2022 17:54

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] Add writing style guide #4271

[docs] Add writing style guide #4271

mattstein commented Oct 7, 2022 •

edited

mattstein commented Oct 7, 2022

rfay left a comment

rfay Oct 7, 2022

mattstein Oct 7, 2022

rfay Oct 7, 2022

rfay Oct 7, 2022

mattstein Oct 7, 2022

mattstein Oct 7, 2022

rfay Oct 7, 2022

mattstein Oct 7, 2022

mayankguptadotcom Oct 7, 2022

rfay Oct 7, 2022

mattstein Oct 7, 2022

rfay Oct 7, 2022

mattstein Oct 7, 2022

rfay Oct 7, 2022

mattstein commented Oct 7, 2022 •

edited

rfay commented Oct 7, 2022 •

edited

mattstein commented Oct 7, 2022 •

edited

mayankguptadotcom left a comment

rfay commented Oct 7, 2022

mayankguptadotcom left a comment

mayankguptadotcom commented Oct 7, 2022

mattstein commented Oct 7, 2022

rfay commented Oct 7, 2022

mattstein commented Oct 7, 2022

rfay commented Oct 8, 2022

mattstein commented Oct 8, 2022

rfay commented Oct 8, 2022

rfay commented Oct 8, 2022

	\| Run `ddev start` and launch the site in a browser. \| Please run `ddev start`, then launch the site in a browser.
	\| Run `ddev start` and launch the site in a browser. \| Please run `ddev start`, then use `ddev launch` to view the site in a browser.

	\| Run `ddev start` and launch the site in a browser. \| Please run `ddev start`, then launch the site in a browser.
	\| Run `ddev start`, then run `ddev launch` to open the site in a browser. \| Please run `ddev start`, then use `ddev launch` to view the site in a browser.


		### Write Once and Link

		Try to keep from repeating yourself in the documentation. Instead, write carefully and link to that well-crafted specimen, whether it’s across the page or off to another section. This has two benefits:

[docs] Add writing style guide #4271

[docs] Add writing style guide #4271

Conversation

mattstein commented Oct 7, 2022 • edited

The Problem/Issue/Bug:

How this PR Solves The Problem:

Manual Testing Instructions:

Related Issue Link(s):

mattstein commented Oct 7, 2022

rfay left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mattstein commented Oct 7, 2022 • edited

rfay commented Oct 7, 2022 • edited

mattstein commented Oct 7, 2022 • edited

mayankguptadotcom left a comment

Choose a reason for hiding this comment

rfay commented Oct 7, 2022

mayankguptadotcom left a comment

Choose a reason for hiding this comment

mayankguptadotcom commented Oct 7, 2022

mattstein commented Oct 7, 2022

rfay commented Oct 7, 2022

mattstein commented Oct 7, 2022

rfay commented Oct 8, 2022

mattstein commented Oct 8, 2022

rfay commented Oct 8, 2022

rfay commented Oct 8, 2022

mattstein commented Oct 7, 2022 •

edited

mattstein commented Oct 7, 2022 •

edited

rfay commented Oct 7, 2022 •

edited

mattstein commented Oct 7, 2022 •

edited