Writing style: additions, improvements #248
Conversation
The two conventions should not be at the same level as the heading that pleads for writers to follow the conventions
A first attempt to express the multiple conventions.
documentation/content/en/books/fdp-primer/writing-style/_index.adoc
Outdated
Show resolved
Hide resolved
An acronym without enclosure characters is followed by direction to always use the characters.
grahamperrin
changed the title
Internal link to an anchor in the same page.
Briefly demonstrate how to link to a manual page. Looking ahead: this might be better at or around https://docs.freebsd.org/en/books/fdp-primer/asciidoctor-primer/#asciidoctor-links For now: present a tip, below the correct way to refer to a manual page – for newcomers to get a better idea of how to write what's required (including use of a FreeBSD-defined macro).
Attention to the FreeBSD-defined Vale rule, with reference to the sentence-spacing anchor in the same page.
| @@ -321,7 +352,7 @@ This rule proposes better wording. | |||
|
|
|||
| . FreeBSD.Hyphens: Often adverbs ending with 'ly' are added with a hyphen which is wrong. | |||
|
|
|||
| . FreeBSD.Spacing: Often double spaces are hard to catch with the naked eye and this is addressed here. | |||
There was a problem hiding this comment.
Was the presence of a listing for this rule consistent with the NO below?
Line 27 in ac4fd34
| @@ -321,7 +352,7 @@ This rule proposes better wording. | |||
|
|
|||
| . FreeBSD.Hyphens: Often adverbs ending with 'ly' are added with a hyphen which is wrong. | |||
|
|
|||
| . FreeBSD.Spacing: Often double spaces are hard to catch with the naked eye and this is addressed here. | |||
| . FreeBSD.Spacing: Between a pair of sentences, it may be incorrect to have two spaces (see link:{sentence-spacing}[spacing between sentences]). | |||
There was a problem hiding this comment.
https://github.com/freebsd/freebsd-doc/tree/main/.vale/styles/FreeBSD
- I can not see a related
.ymlfile - am I looking in the wrong place?
|
Please create a review in phabricator and add the doceng team. |
|
Before this goes to Phabricator, can someone answer the two questions? I don't want to go there with something that's obviously wrong. |
|
The purpose of phabricator is exactly that, make comments on the changes and decide if it’s ok or not |
| [TIP] | ||
| ==== | ||
| `man:csh[1]` -- `man:` for the FreeBSD-defined _ManPageMacro_, `csh` names a page and `[1]` specifies the section of the manual from which the named page is taken. | ||
| ==== |
There was a problem hiding this comment.
|
Please don't use pull request in the main repository as the personal working area. Every event in this repository generates a notification to the watcher and that caused unnecessary alarm and cause other important ones got overwhelmed. The personal fork is exactly for this purpose and please use it before the change is ready for review. |
Are settings somehow not effective?
|
Are you telling everyone to customize notification for all your WIP and when you create a new one? Things should not work like this... |
This comment was marked as resolved.
This comment was marked as resolved.
I don't really understand what you mean, but you can still create a pull request in your fork, and invite people to join review. That could be a better workflow for not letting all your WIPs overwhelm other important information. |
https://github.com/freebsd/freebsd-doc/forks?include=active&page=1&sort_by=open_pull_request_counts apparently zero at the time of writing. Please know that the UX is inferior. |
This comment was marked as resolved.
This comment was marked as resolved.
Some mailing lists are largely populated by notifications from Bugzilla. I don't complain about these notifications. I sometimes set the preference in Bugzilla to not receive notifications. |
This is the purpose of phabricator… |
Yes, but you can configure this in a mailing list. We cannot make this configuration for each PR you open here, this is the problem. |
No. A person might prefer to click Status
|
I found the answer to my question. I'll hide it as resolved. |
|
So, can you please move all the drafts to your personal fork, close in the FreeBSD repo and when are ready open a review in phabricator? |
You misunderstand the workflow. People want to work on something else, they create a fork of a repository, and doing their work in a branch locally or in the personal fork. When the work is done and ready for review. Submit a pull request to official repository or phabricator (currently preferred) and people watch those repositories will be notified and will start the review and comment. Don't do it before things are actually ready so people won't be notified by your WIP. Of course people can click on that status button, but that's for suppressing the "PR ready for review they don't want to follow", not for a PR which shouldn't be created yet. Why ask others to do more things while you can do the right thing in the beginning? If you really want to check what your PR will be like, and invite people to review or comment or WIP, create a pull request to your personal fork first, then invite people can help you. After you're comfortable for more formal review, you can create another pull request to this main repository, or phabricator. Just buzzing everyone isn't the most helpful way to get things done. Trust me, I am happy to review your code and provide comments, but if there is overwhelming notification on all your actions, that will become a distraction instead. |
Is there a move feature? The question was specific to an overview of comments. I found this overview, however it's too simplistic: no overview of what's outstanding, and so on. |
No, but as Li-Wen pointed, you can create a fork and then open PR on your own fork, and then when the PR it’s ready open a review in phabricator. Edit: Or if the functionality exists, I’m not aware of it |
Do you mean, for the list administrator to reject notification emails from Bugzilla? As an end user of a list, for example:
– I see no way to to filter. |
Graham, we need to focus in the problem here. Can you please move all your PR to your personal fork? Thanks. |
Key point:
|
https://docs.freebsd.org/en/books/fdp-primer/writing-style/
The two existing conventions should not be headed at the same level as the heading that pleads for writers to follow the two.
Add the conventions that apply to spacing between sentences.
Mark up an acronym, as it should be marked.
Demonstrate the macro:page[section] approach to linking to a manual page.
Attention to the listing for the FreeBSD-defined FreeBSD.Spacing rule for Vale.