docusaurus icon indicating copy to clipboard operation
docusaurus copied to clipboard

Published 20 hours ago • verified publisher icon wechaty

wechaty doc update

Open hcfw007 opened this issue 2 years ago • 11 comments

I am planning on a major update for wechaty API document, considering there are many elementary wechaty related enquries since we launched workpro. Most of our customers are from China, however the official website of wechaty is in English. So i'll try to make it bilingual. After discussion, we decided to use built-in i18n module to provided bilingual support, even though most of our pages do not have bilingual version. The major work will be done in my spare time, or when I finished most of my work and want to do something less-challenging. So it might take a while. I'll post the new version of Wechaty page in English this two days so you guys can advise on styles and other matters. Please feel free to suggest or comment.

WIP Tracker

  • [x] Wechaty #1514
  • [ ] Bot Doc https://github.com/wechaty/docusaurus/pull/1527
    • [ ] Section 1: Overview

hcfw007 avatar Jan 30 '23 08:01 hcfw007

WIP Tracker

moved to main thread

hcfw007 avatar Jan 30 '23 11:01 hcfw007

Actually I think we should add i18n to the whole wechaty doc website, instead of adding specific chinese doc page, change the whole website to be english/chinese should be a better solution.

windmemory avatar Jan 30 '23 13:01 windmemory

That is also a potential solution. I did not use this method initially because I thought only a few pages capable of changing language is kinda wierd with a website level switch.

hcfw007 avatar Jan 30 '23 13:01 hcfw007

please compare these two approaches and tell me which one you like

  • [x] with built-in i18n: https://github.com/wechaty/docusaurus/pull/1514
  • [ ] with serperate submenu: https://github.com/wechaty/docusaurus/pull/1513

hcfw007 avatar Jan 31 '23 04:01 hcfw007

please compare these two approaches and tell me which one you like with built-in i18n: #1514 with serperate submenu: #1513

Vote for build-in i18n

windmemory avatar Jan 31 '23 05:01 windmemory

I'll start working on it if no one else votes in 1 day.

hcfw007 avatar Jan 31 '23 11:01 hcfw007

@huan any suggestions?

hcfw007 avatar Feb 01 '23 06:02 hcfw007

I have no time to go through it in detail, but I like your idea for improving the docs.

Please go ahead with the most basic part of the docs (like fixing incorrect docs & examples) first, and I will give you feedback when I have time.

Thank you very much for pushing this moving forward!

huan avatar Feb 01 '23 07:02 huan

Updates:

I'm working on PRs about wechaty doc. The English version should be done bofre this Thursday. The doc will be divided into two major parts, For Bot Developers and For Puppet Developers. Detailed Doc Chapters

Bot:

  • Intro: Base info, 6-line bot demo, version changelog
  • Install: How to install dependencies
  • Hello World: Base concepts, create bot, listen to events, lifecycle, ding-dong bot
  • User modules:
    • Message
    • Contact
    • Room
    • ...
  • Events

Puppet:

  • Intro: Wechaty architecture, Why we need a puppet class, Example of servering open-source puppets, version chagnelog.
  • Install: same with bot.
  • Hello World. How to setup an easist bot with MessageSendText only. (based on a hypothetical IM)
  • Abstract methods of user modules:
    • ...UserModules
  • Pack puppet into service with Wechaty-Puppet-Service

hcfw007 avatar May 15 '23 08:05 hcfw007

Chinese version should also be expected.

hcfw007 avatar May 15 '23 08:05 hcfw007

I have recorede a video for i18n PR (https://github.com/wechaty/docusaurus/pull/1514). As you can see, the pages with a Chinese version can be displayed in Chinese, and the pages without one will remain in English (and will not be 404).

https://github.com/wechaty/docusaurus/assets/13669999/e4de83e0-ca6a-4595-837b-abeeb0f98efa

hcfw007 avatar May 15 '23 09:05 hcfw007