French documentation

[tmaziere]

We are working here in Normandy on different software based on Farmbot stack, in collaboration with around twenty training organizations and (high) schools. As testers of this Python library, we would like to document it in French for our partners, and to suggest to other French people to use it. So could we help by translating (part of) the documentation and examples?

If you agree, how should we contribute in terms of repo structure?

[RickCarlino]

This is a good question @tmaziere !

I will discuss this with the team today and get you a full response.

[RickCarlino]

Hi @tmaziere sorry for the slow response.

Here's how I think it would be best to proceed:

1. First, we must ensure that the current README.md is adequate- do you think the current README is enough for a developer to get started? How might we improve the documentation before translation?
2. Once you are ready, you may provide us a translated version of README.md in a pull request. Please name the file README-fr.md.
3. After merging, I will update the README to point to the french documentation.

Eventually, we would like to translate the documentation at developer.farm.bot, but I am unsure if we have the resources to re-write our documentation build system to support internationalization yet.

Please let me know if this will work for your organization. Speak soon!

[tmaziere]

Hi @RickCarlino We fully agree with this principle. I take the time to ask @tberriot for his opinion and I will tell you soon about the current README.md content.

[tmaziere]

Hi @RickCarlino

The README is very clear like that. We have thought about useful examples in an educational context (entering commands via a prompt, integrating the handler into a minimal application) but it may be a little too specific.

The following part is not easy for beginners, but I don't know how to complete it without going too far (and i'm not a big expert in python multithreading, to be honest):

Keep in mind that connect() will block the current thread. If you require parallel operations, consider using a background thread or a worker process.

So if that's OK for you, we'll translate the README as is.

[RickCarlino]

The README is very clear like that.

Great! :tada:

We have thought about useful examples in an educational context (entering commands via a prompt, integrating the handler into a minimal application) but it may be a little too specific.

I would very much like to create a "FarmBotPy Recipe Book". If you write them in French, I would be interested in translating them back to English. We might then be able to put them in our curriculum portal or the developer portal.

The following part is not easy for beginners

I agree :100: percent with this statement. Multiprocessing is a hard concept for beginners. In actuality, the majority of the hours spent on FarmBotPy were spent on finding ways to "hide" this from users. Our situation is complicated because programming a FarmBot is an event-based system (requires multiprocessing). We could have added "better" ways to deal with it, like using Asyncio, but I felt it would be too hard to learn for an entry-level developer.

Would it be more helpful if we made the words even more simple? My intent with that paragraph was to warn users that once your script starts listening to FarmBot, it can't do anything else.

Would this wording be easier to understand?:

Once `connect` is called, execution of all other code will be paused until an event occurs, such as logs, errors, status updates, etc..

If you need to run other code while `connect()` is running, consider using tools like system threads or processes. 

Please let me know and I can update the document.

Have a great weekend.

[tmaziere]

Hi @RickCarlino

Yes, i think the new wording is better! And we will try to produce/share examples all along the french project.

I will translate the README file asap.

Have a nice day!

[RickCarlino]

@tmaziere The README has been updated. Thanks for your suggestion.