Botframework-webchat: WebChat docs on GitHub are comprehensive but are not translated

[ovishesh]

Feature Request

My team and I were working with quite a few Japanese customers where we were trying to customize WebChat using the ReadMe docs here on GitHub. Non-English speakers had an incredibly difficult time implementing WebChat on their own. The official documentation does not have enough documentation on customizing WebChat, and the docs on GitHub are not translated. On top of that, there are paragraphs of text to sort through multiple implementations. We had to point out the exact code snippet that the customers could use to implement WebChat. It went a step beyond hand-holding and some folks felt that it would have been impossible without an English speaker with tribal knowledge to get the non-english speakers through this task.

It will be great to see this comprehensive docs migrate over to docs.microsoft.com.

[Enhancement]

[compulim]

Love this idea. I am unsure how much efforts for putting them on docs.microsoft.com. Their shipping schedule could be different, meaning the docs could come in late. And if devs in our team (primarily me) is up to Microsoft standard on technical writing. I might need to attend some training classes too.

But on the other hand, as Web Chat grown to be complicated, our doc today is not very structured, docs.microsoft.com would help that. People tends to hate GitHub Wiki. 🤔

[ovishesh]

@compulim I agree. It would be an effort but definitely will pay off to the non-english speaking developers as we observed in Japan a few weeks ago. We ended up doing some translation of our own repo with the help of some of our Tokyo based colleagues and that was greatly appreciated by the developers. In saying that, it won't scale out across all MSFT docs supported language on GitHub, so docs.microsoft.com might be a better home.

[corinagum]

Discussed with @cwhitten and @compulim - I am assigning @Kaiqb for 4.5!
Super excited for this. @Kaiqb please let us know if you need anything from the Web Chat team.

[ivorb]

@compulim Which docs should move over? I'm seeing the Samples.md and Readme.md as ones that should, but if there are more please list them here. Thanks!

[corinagum]

@ivorb compulim's on vacation, so until he gets back I'll fill in -- I think the embed documentation will be important to move over, but this is lower priority since the code is not live yet.

That's all I can think of at the moment, but if there are others I'll continue posting to this issue.

[ivorb]

@corinagum we can always add stuff later on, and we've been avoiding putting stuff in the official docs until it's out of preview. So, I think the embed stuff would fall into that category - though as soon as the code is live we can add it.

Thanks!

[corinagum]

@ivorb would Samples.md include write ups for the individual samples? I believe our original use case is that the individual samples provide valuable information that's not translated.

[ivorb]

@corinagum It hadn't, from what I was told from Kamran - doing so would significantly increase the effort and TOC impact, so that would need to be run by Kamran. I'll send him a link to this issue and ask him to chime in.

@Kaiqb?

[corinagum]

@ivorb @Kaiqb We're also happy to coordinate and point out which samples would have the most impact if available to be translated. We can also prioritize an order that we recommend they be translated, if that helps.

[Kaiqb]

@corinagum - we don't put sample pages on the docs.micrsoft.com site. We'll add a link to the main sample page on GitHub.

[corinagum]

@Kaiqb This applies more to having a write up on the samples and linking to the code in our documentation, rather than linking to code from the docs. I believe the Microsoft docs have several articles written that correspond to samples in BotBuilder-Samples.

My concern is that our use case brings up the samples specifically as providing information that is not available in other languages. If we don't address at least some of the samples in article(s), we would not be addressing the original request.

The samples already have extensive readme's that explain the code in detail. Can we consider having this on the docs page?

[ivorb]

Talking to @Kaiqb we don't have individual samples walkthroughs, more task based docs that reference our samples, so he decided to keep it to the main pages. We'll include the main readme (with links to the samples) and the samples page in our docs.

The PR I'm working with for it is: https://github.com/MicrosoftDocs/bot-docs-pr/pull/1543

[corinagum]

@ivorb just FYI link doesn't work, did you need one of us to review? If not, no worries :)

Thanks for the help

[ivorb]

Hmm ok, figured you'd have access to it - not ready for your review yet, but I will want it when it's ready. I'll get it staged on the review site at that time so you can see it there.