SMF Community Helpers > SMF Documentation Help

Making the wiki more personal.

<< < (2/5) > >>

Angelina Belle:
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. :)

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?

Angelina Belle:
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".

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 :)

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...

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



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

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.

Angelina Belle:
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.


[0] Message Index

[#] Next page

[*] Previous page

Go to full version