Topic: Making the wiki more personal.

[K@]

Whilst going through some of the FAQs, checking and adding stuff, I've come-across some sections that refer to "The user", "The user's" and suchlike.

To me, that reads badly.

I've taken the liberty of changing things, like that, to "You", "Your", etc. when I've encountered them.

If you think I'm wrong, in doing that kinda thing, feel free to slap me about with a wet herring.

[emanuele]

http://wiki.simplemachines.org/smf/Help:Documentation_Guidelines
But in the FAQs could be fine.

[K@]

In all honesty, Manny, if I stuck to those guidelines, I'd never add anything.

"PHP" and "HTML" are abbreviations, after all.

I use "it's" and "You're", all the time, too.

No questions?

Now, you REALLY don't want that to happen, do you?

Also, though, what about your actual site? What about restoring the backups?

No "Etc."? Weird.

Seems I've been doing almost everything that one shouldn't...

* K@ fires himself.

[emanuele]

In all honesty, Manny, if I stuck to those guidelines, I'd never add anything.

Then rewrite them.

Guidelines that nobody follow are useless and misleading.

[K@]

My boss might whip me.



Now there's a plan...

[AngelinaBelle]

In FAQs, I am quite happy to have "you" and "your" and suchlike.

For the "this is a boring manual page sections" which are meant mostly to describe a single "page" of the SMF app, the language is more boring and dry. More "professional" more "like a manual page".  That's the standard that Jade passed on, and, generally, those manual pages adhere to those guidelines.  There are some exceptions.

K@ -- I do read your work. Not every single word.  I think you are doing just fine. Generally, you produce something that is a friendly read, and easy to understand.  Whenever you have critiqued my work, you have made useful suggestions. 

No complaints. No whips.  Sorry.
P.S.  I'm not your boss.

[K@]

You kinda are, O leader.

When I write stuff, I tend to try and remember "Friendly".

If a noob's reading that stuff, it can get a bit confusing and, dare I say, like they're kinda orders?

I tend to try and write stuff as though I have a friendly arm around their back, guiding them, you know?

[AngelinaBelle]

I've actually been thinking about this quite a bit, on and off, especially since you started in docs, K@, and I know I've mentioned it to you before.  But since you've asked, I've actually tried to put some of it down in the guidelines.

Does the new version make sense? Are these guidelines going to be good for the different types of documentation we aim to deliver?

I want a balance between "friendly arm around one person's back", and "thing that will be useful to lots of users for some time into the future".

http://wiki.simplemachines.org/smf/Help:Documentation_Guidelines

Thanks for letting me know.

P.S. -- I think my role is more like "coordinator" (oh look, that's in my title already. Thanks, Amacythe!). If I get too "bossy", well, that could kind of get in the way of making good ideas happen.  I inherited this idea from groundup because, well, he was my "boss" at the time

[K@]

Your style's perfect, with me.

When you need to, you can boss, just as any woman can. [/tongue in cheek]

But, usually, you cajole and suggest, which is, as we say over here, the bollox.

All I can say to...

Proper Grammar and Spelling - As taught in US High Schools.

is

No Contractions - Write "it is," never "it's." Write "do not," never "don't"

Just curious. Why not? Most people just don't talk that way. Arm-around-the-back it ain't.

What I REALLY wouldn't mind, in all honesty, is for you/whoever to go around putting anything I "transgress" with, right.

But, typing in that fashion is just too alien, to me. It's coz I'm ancient and stuck in my ways, I guess.

But, really. If my stuff needs Americanis(z)ing, or anything, I'm not gonna cry, if someone does that.

[AngelinaBelle]

OK.  I might have inherited the "US highschool" thing.  That can be improved.  I don't know how to generalize. How do you describe, in the UK, students in the last 3 or 4 years before graduationg from school?

The reason for not having contractions is that they can sometimes be confusing to non-English speakers.
I believe I picked that one up in a guide for writing "Simple English" (for technical manuals).

From time to time, I do edit your work, K@.  Most of the time, I leave your work as-is, or just add wikify it.
If I have any major disagreements, I'll bring them up.

I'm quite happy with your ideas and additions, especially to the FAQs, and I am also happy to continue discussing any of the things in the Documentation Guidelines.

The goal is to make the documentation helpful. To do that, I want it to be simple and clear for readers from all over the world. And everything in the guidelines should support that.  I think.

[ApplianceJunk]

Nice Kitty

[K@]

I think we have a system we can work with.

I'm kinda assuming that Yankglish is actually in more common use, around the world, now, than "proper" English is, sadly.

So, having things in that "language" is, probably, for the best.

But, of course, it's entirely unnatural, for me, to use that. Heck, I don't even know how you spell some words!

So, "correcting" that kinda thing is an obvious thing to do and I have no problem, with that, at all.

Nice Kitty

[AngelinaBelle]

Correct british grammar is also OK by me.
British spelling probably should be OK, too.

("the dog's bollux", or "chuffed" are not grammar issues, but slang/idiom that wouldn't be understood worldwide)

what do you call the British equiv. of our high schools?

[K@]

You know, I'm not too sure, now.

Just "Secondary" schools, I'd guess.

From age eleven to about sixteen?

Infants and juniors are "Primary", so I guess "Secondary" covers the next level. After that, it's college, uni and all that stuff.

I'm guessing that there exists, somewhere an "International English" standard, somewhere. ISO, perhaps?

Still, as long as we stuck with "Understandable English", all'll be good, methinks, ay?

(I won't type Cockney, which is my native tongue. Although, a "Rhyming slang" language pack could be fun to try and work on.)

[AngelinaBelle]

So just "Good Grammer", then.

Cockney? Still call us yanks "Septic"?

[K@]

When we're feeling charitable, yeah.

[AngelinaBelle]

Thanks awfully.

[K@]

[Joshua Dickerson]

Please don't start mixing British English with American English. Customize not Customise. It is going to cause so many issues.

Translate it to English English if we want to do that.

When I think of good style of writing technically, I look at PHP and MySQL. There is a good mix of second and third person speech. Professionally friendly is a good way of looking at it. The best part of a wiki is that if something just doesn't sound right, someone can come along and change it.

[K@]

I figured that what I'd do, is make things so that they look right, to me.

If someone else, then, decides to change it, that's up to them.

I don't "Watch" stuff.

But, to type in Americanese would be difficult, because I simply don't know how they spell some words.

Oh, I know about "Colour" and "Color" and a few of the obvious ones. But, some of their words,  sentence-construction and stuff has me totally baffled.

So, as I said, I'll do what I do and people can change it to their heart's content. I really have no problem, with that, unless someone decides to tell everyone that I was the author.

I must confess to altering a few things, myself, because, having read them, I thought "That just reads very badly and could be taken in a number of different ways". So, I've edited them to try and make them crystal-clear.

I also edited some, where they've said "The user", to say "You", coz it just sounds so much more, well, personal and friendly.