Docs translation about itertools-php HOT 18 CLOSED

Hi @Smoren,

MathPHP solves a real problem that many people have: they need some math functionality, and PHP doesn't natively provide it. And honestly, I wasn't initially making it for other people. I needed some math functionality at work and coming up short finding any existing functionality, just decided to make the library I'd want to use.

Also, the name is pretty self explanatory. The name MathPHP pretty much tells you everything you need to know. It also helps that we test thoroughly and instill confidence over time that the math is correct. The project has been around since 2016, so it has had time to organically grow in popularity. Or it could just be that people love the Professor Elephant logo.

I didn't do much to advertise it. I posted once or twice in the PHP subReddit about it, and I think long-time contributor @Beakerboy also posted in some Math subReddits about it. I think the PHPStorm people at JetBrains follow that subreddit because shortly after posting they also added it to their monthly PHP Annotated blog posts (April 2020 and October 2020). I probably could have done more I suppose.

For IterTools, I think the main thing to consider is that people may not intuitively know they want something like this. It's not like math where they have an immediate problem of needing a linear regression or standard distribution and are actively searching for something to solve their problem. If you don't already know that zip is a thing, you may not know to look for it. And you could probably struggle to do something similar using a for loop and manually indexes into multiple arrays simultaneously. It would be way better for them to just use IterTools zip, but if they don't know that is a thing, they won't know they should look for it.

One way to increase awareness is to relate it to things they already know. For a Python programmer, they probably know what IterTools is just on the name. And a Java programmer would understand what Streams are based on the name. These days, it's hard to imagine programming in Java without using Streams, but that kind of transition and awareness took time.

FYI: PHP Annotated did mention IterTools PHP in their July 2022 issue. A lot more has been added since then, so it might make sense to ping them again to add it again.

Or maybe Professor Elephant moonlighting as a construction worker is the key here and just post him somewhere highly visible to gain attention, I'm not a marketing expert =) I understand and agree with your sentiment though. I think the functionality provided in IterTools solves a lot of common problems, allows you to write clean, concise, and intuitive code. I think a lot of people would benefit from it. Just have to get the word out I suppose.

from itertools-php.

Hi @Smoren,

Thank you so much for translating the documentation. This is a great idea to make it more accessible to a larger audience.

How about a docs directory in the IterTools repo. It is possible there may be other translations in the future, even if just one today. And somewhere on the main README let's put a link to translations of the documentation.

If I add something new to the main English README, I'll have to create a log somewhere to make sure that fact does not get lost so we can keep translations up to date. Or maybe just an ongoing Github issue for documentation to communicate changes. Keep it simple.

Thanks again for doing this. Facilitating communication and overcoming language barriers is always a good thing.
Mark

from itertools-php.

Hi, @markrogoyski,

I'm glad you liked this idea.

I propose such a plan: when the development branch is ready for release, start an issue, and I will update the translation of the documentation.

BTW, how soon do you plan to release?

from itertools-php.

Hi @Smoren,

A Github issue sounds good. Let's try that.

A lot of features have been added and I think Stream is in a good place with the current feature set so I will probably do a release soon if I have a chance if that works for you.

Thanks,
Mark

from itertools-php.

Hi @markrogoyski,

I think it's a good idea to do a release after merging Set operations: intersection and symmetricDifference.

Do you agree with me?

from itertools-php.

Hi @Smoren,

Sounds good. I'll wait until the set operations are merged in.

from itertools-php.

Hi @markrogoyski,

I think we are ready to do a release. Do you agree with me?

I also think we need a separate branch named release-candidate to make a PR with translation into it and to free develop branch for new features.

from itertools-php.

Hi @Smoren,

I have some README documentation still to add and clean up. Everything else looks good. I'll do a release as soon as I get everything documented.

After I merge and release, just do a PR against the main branch for the document translation. Documentation translations can be added at any time and don't require a release or to hold up a release.

Thanks again for working on a translation!
Mark

from itertools-php.

@markrogoyski OK, thanks!

from itertools-php.

Hi @Smoren,

I've released v.1.2.0 with all the latest new features. Thanks for all the contributes that went into this!

Whenever you are ready to submit a README translation, submit a PR with a file named README-RU.md in the docs directory. In the main README we'll put a section for document translations with a link to each one. Something like this where each language is written in its own script and will be a link to the translated README:

README docs translated in other languages

• Русский
• Español
• 日本語

(Apologies if I wrote Russian wrong, as I don't speak that language).

BTW, apologies that I have since updated the README quite a bit since you did your initial translation. I'll try to limit editing it going forward to prevent additional translation work.

Thanks again!
Mark

from itertools-php.

Hi @markrogoyski,

I've created a PR with the translation.

from itertools-php.

Hi @Smoren,

I've added some new functionality in the develop branch along with new content in the English README. What would be the easiest process to keep the translations aligned? I was thinking of two approaches:

1. Add the same English stub content to the translated READMEs to be translated later. This keeps it up to date, although will have mixed language content until it is translated.
2. Just keep a Github issue around and mention the changes/commits that update the README. Update translations over time.

Thoughts?
Mark

from itertools-php.

Hi @markrogoyski,

I think the best way is to open a new issue at pre-release time with a list of changes of the existing methods descriptions and of changes in the README structure.

New methods I can find in CHANGELOG file.

I think it's about a lot of iterations to support the translation during development.

from itertools-php.

@markrogoyski,

By the way, offtopic. I wanted to ask you how MathPHP became such a popular library and what can we do to similarly popularize IterTools?

from itertools-php.

I'll have to look at this project....no idea what it is but I'll probably find a way to use it.

from itertools-php.

Thank you @markrogoyski for the detailed answer. I totally agree with your arguments and conclusions.

Now I'm telling friends and colleagues about IterTools, showing examples of its real application in work tasks. In addition, I launched an advertising campaign on the Russian social network VK.

I am sure that when a wide community learns about this library and actively uses it, PHP will become an even more attractive language for experienced developers.

from itertools-php.

@markrogoyski,

Offtop: I like your idea about mascot and I asked an artist friend to draw something similar for one of my repositories. Seems to look good too :)

from itertools-php.

Nice. Paper airplanes go in--rocket ships come out!

from itertools-php.