Nit-Picking Newbie

Since my background is programming / math / science / English prose rather than visual design / markup / typography, MODx "feels" quite natural. So far, MODx is working flawlessly for me. The default-installed and contributed snippets are a wonderful resource, and the Manager is capable beyond my expectations.

However, errors of English grammar, syntax, spelling and punctuation in the documentation undermine the impression of quality. Too frequently do I find myself in that zone of happy MODx contemplation and learning, only to be jarred out of it by a pretzel paragraph, some homonymic horror, plurality confused with possession, a post-fixed preposition, etc.

I am glad to report problems I encounter if that would be useful, but whither and how?

I remember reading somewhere that the best way would be to blog your ’better-english’ version of the documentation and/or post it on the forum. I find that the Modx developers closely follow the forum posts and would grab and use any good work. This seems like an unstructured system and maybe somewhere else you would find a documentation group with volunteers registering to work. But having watched how such efforts have failed in the case of other opensource development efforts, this perhaps is a practical approach.

Nice of you to offer doing this. Modx particularly the upcoming Revolution documentation could do with a lot of improvement particularly for newbies like you and I to understand the new version.

It’s very easy to get yourself an editing login for the old wiki ("create account", top right), then you can just hop in and fix those errant apostrophes. There is a checkbox to describe the update as a "minor edit". I’m not sure what the scene is with the new wiki - it would be handy to have the strategy for it laid out.

Meanwhile, I suggest you can improve a very large percentage of most computer project documentation by getting just three things across:
[table]
[tr][td] [/td][td]it’s = it is[/td][td]its = belonging to it[/td][/tr]
[tr][td] [/td][td]loose = not tight (adjective) or unleash (verb)[/td][td]lose = not have any more[/td][/tr]
[tr][td] [/td][td]principle = fundamental truth[/td][td]principal = main (adjective) or school head (noun)[/td][/tr]
[/table]

KP

Keep in mind that MODx is very much an international open-source project, and while someone’s code may be flawless to the point of brilliance, that doesn’t mean that their English will be quite up to that level.

And as has been said above, we greatly appreciate your offer to step in and give us a hand with improving the documentation

Dear kp52 and others,

Did you hear the one about the bellicose yet apparently pacific and generally confused playwright who recommended "Cry havoc and let lose the dogs of war?" Ouch! To read such is a stab in the back.

In all seriousness, is there not a Forum thread for reporting documentation problems? (I’m reluctant to touch live documentation.)

Quote from: halfnium at Mar 14, 2010, 01:26 AM

In all seriousness, is there not a Forum thread for reporting documentation problems? (I’m reluctant to touch live documentation.)

I just scrolled the forum list for half a minute and found this Documentation, Tips & Tricks
Instructions, Demos, Insight and How-Tos. Child Boards: Documentation Suggestions & Corrections

Is this what you wanted?

If you put it in the Document Suggestions and Corrections forum, it will definitely get looked at and, if someone has the time, it will get fixed. Bear in mind that the standards for online documentation for an Open Source project are not the same as those for a graduate-level English paper.

That said, glaring errors in grammar or usage should definitely be fixed.

Thanks for your willingness to contribute.

Dear indeman,

Thank you. Document Suggestions and Corrections looks like the right place. I’ll open a topic and add issues and suggestions as I encounter them.

My effort to find that board failed. Rather than browse the Forum, I searched on keywords such as "grammar," "typo" and "punctuation." Hits on these keywords were scattered around the Forum, but they did not lead me to that board.

BTW, give that board a visit. Few of its topics relate to documentation except in the sense that users can’t figure out some aspect of MODx by themselves through the documentation.

-- Halfnium

Quote from: halfnium at Mar 14, 2010, 06:10 PM

Dear indeman,
Thank you. Document Suggestions and Corrections looks like the right place. I’ll open a topic and add issues and suggestions as I encounter them.

you are welcome.
Quote from: halfnium at Mar 14, 2010, 06:10 PM

My effort to find that board failed. Rather than browse the Forum, I searched on keywords such as "grammar," "typo" and "punctuation." Hits on these keywords were scattered around the Forum, but they did not lead me to that board.

Yes, unless those keywords appear in the titles or in past posts, your search will not find the board.
Quote from: halfnium at Mar 14, 2010, 06:10 PM

BTW, give that board a visit. Few of its topics relate to documentation except in the sense that users can’t figure out some aspect of MODx by themselves through the documentation.

The posts to such community forums do not require moderators approval. Some other forums have dedicated moderators who dilligently do housekeeping and move the posts to appropriate forums or delete inappropriate posts. Even this thread would have been moved to the documentation board or suggestions & corrections sub-board. Modx community forums are largely self regulated by the community members thus far.
Maybe when the number of users become unmanageable and threads get tangled in knots, there would be an effort to recruit volunteers to manage/moderate/housekeep the forums.

Thank you again for volunteering

indieman, every board does in fact have its moderator. The rules are not particularly strict, however. That particular board has two moderators; actually I’m one of them. Occasionally the topic wanders a bit, but as long as it’s generally discussing the documentation I leave it alone.