You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@pulsar.apache.org by Yu <li...@apache.org> on 2021/12/15 03:17:45 UTC
PIP 116: Create Pulsar Writing Style Guide
Hi Pulsar enthusiasts,
As you may notice, there are more and more documentation contributions
nowadays, which is great!
Similar to coding style guides, in the field of technical writing, a
writing style guide is a must to improve users' experience and eliminate
writers' workload.
To improve the doc quality, I create our style guide — *Pulsar Writing
Style Guide* [1]
# Definition
Pulsar Writing Style Guide contains a set of standards for writing and
designing content.
It helps maintain a consistent style, voice, and tone across Pulsar
documentation.
This guide is inspired by some existing style guides. It references *IBM
Style Guide*, *Chicago Manual of Style*, and other books for more
exhaustive guidance.
# Benefits
Pulsar Writing Style Guide can improve the content quality and bring many
benefits to users and writers like:
For users:
- Make documentation easier to read
- Reduce users’ cognitive load
- Increase users' confidence in the content’s authority
For information developers:
- Resolve arguments and support our needs to create readable, usable, and
minimalist information
- Save time and trouble by providing a single reference for writing about
common topics, features, and more
- Help write documentation in a clearer way and keep a consistent tone of
voice and style
>>>>>>
This guide is not a one-shot job, the current version is an initial draft.
I'll make continuous efforts on that.
I believe that the Pulsar community will welcome this addition to our
resources and profit from the instructions.
Feel free to comment, thanks.
[1]
https://docs.google.com/document/d/1lc5j4RtuLIzlEYCBo97AC8-U_3Erzs_lxpkDuseU0n4/edit#
Re: PIP 116: Create Pulsar Writing Style Guide
Posted by Yu Liu <yu...@streamnative.io>.
Hi Haiting,
There are no automatic tools to check **all** writing style issues, but
they can help check some.
Steps see
https://docs.google.com/document/d/1Qw7LHQdXWBW9t2-r-A7QdFDBwmZh6ytB4guwMoXHqc0/edit
Hi Dave,
Thanks! I've incorporated your comments.
On Thu, Dec 16, 2021 at 2:34 AM Dave Fisher <wa...@apache.org> wrote:
> Thanks Yu for this initiative.
>
> I made a small correction in the document.
>
> Regards,
> Dave
>
> > On Dec 14, 2021, at 7:17 PM, Yu <li...@apache.org> wrote:
> >
> > Hi Pulsar enthusiasts,
> >
> >
> > As you may notice, there are more and more documentation contributions
> > nowadays, which is great!
> >
> >
> > Similar to coding style guides, in the field of technical writing, a
> > writing style guide is a must to improve users' experience and eliminate
> > writers' workload.
> >
> >
> > To improve the doc quality, I create our style guide — *Pulsar Writing
> > Style Guide* [1]
> >
> >
> > # Definition
> >
> >
> > Pulsar Writing Style Guide contains a set of standards for writing and
> > designing content.
> >
> >
> > It helps maintain a consistent style, voice, and tone across Pulsar
> > documentation.
> >
> >
> > This guide is inspired by some existing style guides. It references *IBM
> > Style Guide*, *Chicago Manual of Style*, and other books for more
> > exhaustive guidance.
> >
> >
> > # Benefits
> >
> >
> > Pulsar Writing Style Guide can improve the content quality and bring many
> > benefits to users and writers like:
> >
> >
> > For users:
> >
> > - Make documentation easier to read
> >
> > - Reduce users’ cognitive load
> >
> > - Increase users' confidence in the content’s authority
> >
> >
> > For information developers:
> >
> > - Resolve arguments and support our needs to create readable, usable, and
> > minimalist information
> >
> > - Save time and trouble by providing a single reference for writing about
> > common topics, features, and more
> >
> > - Help write documentation in a clearer way and keep a consistent tone of
> > voice and style
> >
> >
> >>>>>>>
> >
> >
> > This guide is not a one-shot job, the current version is an initial
> draft.
> > I'll make continuous efforts on that.
> >
> >
> > I believe that the Pulsar community will welcome this addition to our
> > resources and profit from the instructions.
> >
> >
> > Feel free to comment, thanks.
> >
> >
> > [1]
> >
> https://docs.google.com/document/d/1lc5j4RtuLIzlEYCBo97AC8-U_3Erzs_lxpkDuseU0n4/edit#
>
>
Re: PIP 116: Create Pulsar Writing Style Guide
Posted by Yu Liu <yu...@streamnative.io.INVALID>.
Hi Haiting,
There are no automatic tools to check **all** writing style issues, but
they can help check some.
Steps see
https://docs.google.com/document/d/1Qw7LHQdXWBW9t2-r-A7QdFDBwmZh6ytB4guwMoXHqc0/edit
Hi Dave,
Thanks! I've incorporated your comments.
On Thu, Dec 16, 2021 at 2:34 AM Dave Fisher <wa...@apache.org> wrote:
> Thanks Yu for this initiative.
>
> I made a small correction in the document.
>
> Regards,
> Dave
>
> > On Dec 14, 2021, at 7:17 PM, Yu <li...@apache.org> wrote:
> >
> > Hi Pulsar enthusiasts,
> >
> >
> > As you may notice, there are more and more documentation contributions
> > nowadays, which is great!
> >
> >
> > Similar to coding style guides, in the field of technical writing, a
> > writing style guide is a must to improve users' experience and eliminate
> > writers' workload.
> >
> >
> > To improve the doc quality, I create our style guide — *Pulsar Writing
> > Style Guide* [1]
> >
> >
> > # Definition
> >
> >
> > Pulsar Writing Style Guide contains a set of standards for writing and
> > designing content.
> >
> >
> > It helps maintain a consistent style, voice, and tone across Pulsar
> > documentation.
> >
> >
> > This guide is inspired by some existing style guides. It references *IBM
> > Style Guide*, *Chicago Manual of Style*, and other books for more
> > exhaustive guidance.
> >
> >
> > # Benefits
> >
> >
> > Pulsar Writing Style Guide can improve the content quality and bring many
> > benefits to users and writers like:
> >
> >
> > For users:
> >
> > - Make documentation easier to read
> >
> > - Reduce users’ cognitive load
> >
> > - Increase users' confidence in the content’s authority
> >
> >
> > For information developers:
> >
> > - Resolve arguments and support our needs to create readable, usable, and
> > minimalist information
> >
> > - Save time and trouble by providing a single reference for writing about
> > common topics, features, and more
> >
> > - Help write documentation in a clearer way and keep a consistent tone of
> > voice and style
> >
> >
> >>>>>>>
> >
> >
> > This guide is not a one-shot job, the current version is an initial
> draft.
> > I'll make continuous efforts on that.
> >
> >
> > I believe that the Pulsar community will welcome this addition to our
> > resources and profit from the instructions.
> >
> >
> > Feel free to comment, thanks.
> >
> >
> > [1]
> >
> https://docs.google.com/document/d/1lc5j4RtuLIzlEYCBo97AC8-U_3Erzs_lxpkDuseU0n4/edit#
>
>
Re: PIP 116: Create Pulsar Writing Style Guide
Posted by Dave Fisher <wa...@apache.org>.
Thanks Yu for this initiative.
I made a small correction in the document.
Regards,
Dave
> On Dec 14, 2021, at 7:17 PM, Yu <li...@apache.org> wrote:
>
> Hi Pulsar enthusiasts,
>
>
> As you may notice, there are more and more documentation contributions
> nowadays, which is great!
>
>
> Similar to coding style guides, in the field of technical writing, a
> writing style guide is a must to improve users' experience and eliminate
> writers' workload.
>
>
> To improve the doc quality, I create our style guide — *Pulsar Writing
> Style Guide* [1]
>
>
> # Definition
>
>
> Pulsar Writing Style Guide contains a set of standards for writing and
> designing content.
>
>
> It helps maintain a consistent style, voice, and tone across Pulsar
> documentation.
>
>
> This guide is inspired by some existing style guides. It references *IBM
> Style Guide*, *Chicago Manual of Style*, and other books for more
> exhaustive guidance.
>
>
> # Benefits
>
>
> Pulsar Writing Style Guide can improve the content quality and bring many
> benefits to users and writers like:
>
>
> For users:
>
> - Make documentation easier to read
>
> - Reduce users’ cognitive load
>
> - Increase users' confidence in the content’s authority
>
>
> For information developers:
>
> - Resolve arguments and support our needs to create readable, usable, and
> minimalist information
>
> - Save time and trouble by providing a single reference for writing about
> common topics, features, and more
>
> - Help write documentation in a clearer way and keep a consistent tone of
> voice and style
>
>
>>>>>>>
>
>
> This guide is not a one-shot job, the current version is an initial draft.
> I'll make continuous efforts on that.
>
>
> I believe that the Pulsar community will welcome this addition to our
> resources and profit from the instructions.
>
>
> Feel free to comment, thanks.
>
>
> [1]
> https://docs.google.com/document/d/1lc5j4RtuLIzlEYCBo97AC8-U_3Erzs_lxpkDuseU0n4/edit#
Re: PIP 116: Create Pulsar Writing Style Guide
Posted by Dave Fisher <wa...@apache.org>.
Thanks Yu for this initiative.
I made a small correction in the document.
Regards,
Dave
> On Dec 14, 2021, at 7:17 PM, Yu <li...@apache.org> wrote:
>
> Hi Pulsar enthusiasts,
>
>
> As you may notice, there are more and more documentation contributions
> nowadays, which is great!
>
>
> Similar to coding style guides, in the field of technical writing, a
> writing style guide is a must to improve users' experience and eliminate
> writers' workload.
>
>
> To improve the doc quality, I create our style guide — *Pulsar Writing
> Style Guide* [1]
>
>
> # Definition
>
>
> Pulsar Writing Style Guide contains a set of standards for writing and
> designing content.
>
>
> It helps maintain a consistent style, voice, and tone across Pulsar
> documentation.
>
>
> This guide is inspired by some existing style guides. It references *IBM
> Style Guide*, *Chicago Manual of Style*, and other books for more
> exhaustive guidance.
>
>
> # Benefits
>
>
> Pulsar Writing Style Guide can improve the content quality and bring many
> benefits to users and writers like:
>
>
> For users:
>
> - Make documentation easier to read
>
> - Reduce users’ cognitive load
>
> - Increase users' confidence in the content’s authority
>
>
> For information developers:
>
> - Resolve arguments and support our needs to create readable, usable, and
> minimalist information
>
> - Save time and trouble by providing a single reference for writing about
> common topics, features, and more
>
> - Help write documentation in a clearer way and keep a consistent tone of
> voice and style
>
>
>>>>>>>
>
>
> This guide is not a one-shot job, the current version is an initial draft.
> I'll make continuous efforts on that.
>
>
> I believe that the Pulsar community will welcome this addition to our
> resources and profit from the instructions.
>
>
> Feel free to comment, thanks.
>
>
> [1]
> https://docs.google.com/document/d/1lc5j4RtuLIzlEYCBo97AC8-U_3Erzs_lxpkDuseU0n4/edit#
Re: PIP 116: Create Pulsar Writing Style Guide
Posted by Haiting Jiang <ji...@apache.org>.
+1, Great stuff.
I am wondering if there is some tool to check it automatically? like code-style check.
Thanks,
Haiting
On 2021/12/15 03:17:45 Yu wrote:
> Hi Pulsar enthusiasts,
>
>
> As you may notice, there are more and more documentation contributions
> nowadays, which is great!
>
>
> Similar to coding style guides, in the field of technical writing, a
> writing style guide is a must to improve users' experience and eliminate
> writers' workload.
>
>
> To improve the doc quality, I create our style guide — *Pulsar Writing
> Style Guide* [1]
>
>
> # Definition
>
>
> Pulsar Writing Style Guide contains a set of standards for writing and
> designing content.
>
>
> It helps maintain a consistent style, voice, and tone across Pulsar
> documentation.
>
>
> This guide is inspired by some existing style guides. It references *IBM
> Style Guide*, *Chicago Manual of Style*, and other books for more
> exhaustive guidance.
>
>
> # Benefits
>
>
> Pulsar Writing Style Guide can improve the content quality and bring many
> benefits to users and writers like:
>
>
> For users:
>
> - Make documentation easier to read
>
> - Reduce users’ cognitive load
>
> - Increase users' confidence in the content’s authority
>
>
> For information developers:
>
> - Resolve arguments and support our needs to create readable, usable, and
> minimalist information
>
> - Save time and trouble by providing a single reference for writing about
> common topics, features, and more
>
> - Help write documentation in a clearer way and keep a consistent tone of
> voice and style
>
>
> >>>>>>
>
>
> This guide is not a one-shot job, the current version is an initial draft.
> I'll make continuous efforts on that.
>
>
> I believe that the Pulsar community will welcome this addition to our
> resources and profit from the instructions.
>
>
> Feel free to comment, thanks.
>
>
> [1]
> https://docs.google.com/document/d/1lc5j4RtuLIzlEYCBo97AC8-U_3Erzs_lxpkDuseU0n4/edit#
>