documentation language

[imbolc]

For me, as not english native speaker, the language of documentation looks much complicated in comparison with most other libs.

[Mike Bayer]

Hello -

I appreciate that SQLAlchemy has a lot of documentation, and that it can benefit from ongoing work in improving sentence structure, adding more examples and cross-linking.

However, these are all things that go on all the time. We accept tickets and pull requests that refer to specific wordings to be improved and clarified.

Given that, how is this raising this issue helping the project? Are there specific areas of improvement you'd like to suggest (helpful) or is this issue just a suggestion that more work needs to be done (not helpful) ?

[imbolc]

I agree that current documentation is complete and detailed. I just mean, it's better to trying to use 1000 most common english words and short, simple sentences where it's possible. Just for popularity among non english native speakers. Thanks :)

[Mike Bayer]

Agree 100%. In particular I'd request that you review the ORM tutorial and SQL Expression tutorial at http://docs.sqlalchemy.org/en/rel_1_0/orm/tutorial.html and http://docs.sqlalchemy.org/en/rel_1_0/core/tutorial.html, which are intended to be the most introductory documentation we have, and please raise specific issues where uncommon words are found as well as run-on sentences. The poor sentence structures found elsewhere should also be located and individual bug reports / pull requests should be proposed. Unfortunately SQLAlchemy's documentation is 95% a one-person job and it is extremely difficult to describe many aspects of it using plain text, and most sections of the documentation have been rewritten many times.

I'd also invite non-native speakers to refer to external literature such as the OReilly book which has had the benefit of full review by multiple professional editors.

Overall, general commentary of this nature without specifics should be raised on the mailing list, thanks!