[GitHub] [pulsar] Jennifer88huang edited a comment on issue #4507: [Docs] Update site2/docs/functions-overview.md

[GitBox <gi...@apache.org>]

Jennifer88huang edited a comment on issue #4507: [Docs] Update site2/docs/functions-overview.md
URL: https://github.com/apache/pulsar/pull/4507#issuecomment-501537238
 
 
   > @jerrypeng  using second-person pronoun is ok with me. I just know from writing academic papers for IEEE or ACM conferences, we always use third person. I don't think I have ever read a academic paper written in second-person. Though our documentation doesn't need to be as formal as an academic paper.
   
   When we write academic paper, we use third person to indicate they are objective opinions. It's requirement of academic paper. When we write technical documentation (user manuals), our target readers are our users, we need adopt user-focus style, and involve them as much as possible. That's why we use second-person pronoun in technical writing.
   When you read user manuals at IEEE website, you will find that their user manuals also adopt second-person pronoun style. The following is an example from IEEE.
   ![image](https://user-images.githubusercontent.com/47805623/59401801-83787600-8dce-11e9-8516-dab1236bc81c.png)
   This does not mean that technical documentation does not need to be as formal as an academic paper. They just adopt different writing styles, in order to achieve different goals.
   When you read Microsoft technical docs, you will find that they also adopt second-person pronoun.
   ![image](https://user-images.githubusercontent.com/47805623/59402063-92135d00-8dcf-11e9-8862-687a779e3fed.png)
   
   > Yes. In some places we use Pulsar Function (capital case "f") in other places we use Pulsar function (lowercase "f"). We probably should be consistent throughout our documentation, though I am not sure which is more appropriate, capital case "f" or lowercase "f".
   > 
   > Though for Azure Functions, its documentation uses a capital case "f":
   > 
   > https://azure.microsoft.com/en-us/services/functions/
   > 
   
   Thank you very much for your information. "Function" is really a challenging noun here. And I totally agree with you that we need keep it consistent throughout our docs.
   
   I read the Azure Functions doc you recommend, they use "Functions" and "functions" at the same time. I guess when they refer to "Azure Functions/Durable Functions/Functions" (as proper noun), they use the uppercase letter; when they refer to other functions (especially created by users), they use lowercase letter. 
   ![image](https://user-images.githubusercontent.com/47805623/59402346-7c526780-8dd0-11e9-91e4-022a7a8f4357.png)
   My suggestion:
   1. When it refers to framework, we use "Pulsar Functions"(plural form and uppercase);
   2. When it refers to individual functions, we use "function/functions"(lowercase). For example, "Java function", "You can create a function..."
   
   Or could we ask others to discuss on this issue and decide how to use this word in our docs? After decision, I can update it throughout.

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services