Jennifer88huang commented on a change in pull request #4485: add docs on how to debug Pulsar Functions URL: https://github.com/apache/pulsar/pull/4485#discussion_r292725990
########## File path: site2/docs/functions-debugging.md ########## @@ -0,0 +1,121 @@ +--- +id: functions-debugging +title: Debugging Pulsar Functions Review comment: @jerrypeng @merlimat Thank you very much for raising this question. Actually, "debugging functions" / "debug functions", "Getting started" / "Get started" are correct as a task topic title. When we write task topics, we can use verb-based, gerunds, or "how-to" titles, either is OK, as long as we keep consistent. Then you might ask why do we change it as "base verb"? Mainly for two reasons. 1. Minimalism writing style: when IBM writers began to advocate minimalism writing in 201x(I'm sorry I forget the exact year) , most writers in other companies begin to accept this style. We write “minimalist,” task-oriented information that quickly meets users’ needs, create effective tasks, and separate tasks from concept and reference topics. In older documentation, task topics are mixed with concepts and references, it is difficult for users to find what they want faster; in new trend, task topics are separated from concept and reference, so users can easily and quickly find what they want. If you read newer IBM docs, they have adopted the new styles. For older version, some are not updated. For example,  However, in [DITA Best Practices](https://www.amazon.com/DITA-Best-Practices-Roadmap-Architecting/dp/0132480522) published by IBM press, verb for task topics are recommended.  In Microsoft documentation, they also adopt the new style, see https://docs.microsoft.com. The following is an example from their website: https://docs.microsoft.com/en-us/azure/devops/get-started/index?view=azure-devops  Pingcap doucmentation also adopt the new trend, their writers are mainly former IBMers. https://pingcap.com/docs/dev/how-to/get-started/local-cluster/install-from-binary/  Concerning AWS doc recommended by @jerrypeng at https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-quick-start.html, we can see that AWS is typically the older docs, mixing tasks with concepts and references. Yet they are also working towards the task-oriented trend, see their task titles:  2. Faster in fuzzy search: Using "base-verb" is easier and faster for users to search information they need. ---------------------------------------------------------------- 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: [email protected] With regards, Apache Git Services
