wechaty / docusaurus

Wechaty Official Website for Documentations, Powered by Docusaurus.
https://wechaty.js.org/docs/
Other
112 stars 345 forks source link

Docs: to keep all recipes as simple as they can, and align to TS #691

Open huan opened 3 years ago

huan commented 3 years ago

The Python version recipe in https://wechaty.js.org/docs/recipes/event has two methods to finish one task, which will puzzle the new developers:

from wechaty import Wechaty, ScanStatus
from typing import Optional
import asyncio

# method one
def on_scan (qrcode, status):
    print('Scan QR Code to login: {}\n'.format(staus))
    print('https://wechaty.js.org/qrcode/{}'.format(qrcode))

bot = Wechaty()
bot.on('scan', on_scan)
asyncio.run(bot.start())

# method two (suggested)
class MyBot(Wechaty):
    async def on_scan(self, qr_code: str, status: ScanStatus, data: Optional[str]):
        """listen scan event"""
        print('Scan QR Code to login: {}\n'.format(staus))
        print('https://wechaty.js.org/qrcode/{}'.format(qrcode))

asyncio.run(MyBot().start())

The goal of the recipe code is to show the new developers how to do a specific task, like receive the scan QR code, I think there are two issues we need to discuss and improve:

  1. We should only give new developers one way to finish one task.
  2. We should try our best to align the usage of the API to the TS version.

So my suggestion would be:

  1. Reduce two methods to one: remove the OOP code in the recipe, only keep the Callback code (method one)
  2. Align all code to TS so that the new developers will get a consistent feeling with our Polyglot Wechaty.

The OOP method can be introduced as an advanced feature in Polyglot Wechaty: Python

@wj-Mcat Please let me know what you think, thank you very much.

huan commented 3 years ago

Quota from https://documentation.divio.com/tutorials/#focus-only-on-the-steps-the-user-needs-to-take

Focus only on the steps the user needs to take

Your tutorial needs to be focused on the task at hand. Maybe the command you’re introducing has many other options, or maybe there are different ways to access a certain API. It doesn’t matter: right now, your learner does not need to know about those in order to make progress.


As the mainstream of the Wechaty ecosystem is planning to focus on Functional Programming and Redux in the future, so I'm going to keep all Polyglot Wechaty documentations to be aligned to the TS Wechaty functional programming methods.

Please feel free to let me know if there are any suggestions.

wj-Mcat commented 3 years ago

@huan Ok, I will remove the suggested method two coding style to align the TS wechaty funcitonal programing methods. It's a great consideration for the whole wechaty documentation.