pulsar-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From GitBox <...@apache.org>
Subject [GitHub] [pulsar] Jennifer88huang commented on a change in pull request #4485: add docs on how to debug Pulsar Functions
Date Wed, 12 Jun 2019 02:27:55 GMT
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, 
   ![image](https://user-images.githubusercontent.com/47805623/59318622-31feb700-8cfa-11e9-9a3e-2e08dbafb296.png)
   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.
   ![image](https://user-images.githubusercontent.com/47805623/59318702-7ab67000-8cfa-11e9-9697-1c0b919f5a8d.png)
   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
   ![image](https://user-images.githubusercontent.com/47805623/59318751-a6d1f100-8cfa-11e9-842a-6a7ef118bd2f.png)
   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/
   ![image](https://user-images.githubusercontent.com/47805623/59319184-4e9bee80-8cfc-11e9-9b89-36cf0a062f52.png)
   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:
   ![image](https://user-images.githubusercontent.com/47805623/59318859-22cc3900-8cfb-11e9-8c8e-630090042ec0.png)
   2. Faster in fuzzy search: Using "base-verb" is easier and faster for users to search information
they need. 
   So we can adopt the new trend in Pulsar docs. If you have any issue with this, feel free
to contact us.

----------------------------------------------------------------
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

Mime
View raw message