Help talk:Documentation Guidelines

From Online Manual

Jump to: navigation, search

Should this guide follow the rules for writing documentation? --AngelinaBelle 11:05, 3 December 2010 (EST)

Passive Voice, Active Voice, and "You"

I think the Wikipedia Manual of Style is a reasonably good guide.

Wikipedia:Wikipedia:YOU has a good example of avoiding You. There's a secion on contractions.

There is nothing at all on passive or active voice, though there is a section on avoiding instructional style in encyclopedic content. In the "here is what this page does" content, we want to avoid instructional style. In the "how to use this page" content, of course, we want to use instructional style, because passive voice is very awkward for instructional content. http://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style#Instructional_and_presumptuous_language

--AngelinaBelle 09:01, 28 January 2011 (EST)

One of the many reasons why I am so happy you've joined the team. The Wikipedia style guide will help us greatly. Since it is CC-SA licensed, lets start with this and then add and remove where we need to. I also like the Y! Style Guide because it contains information that isn't directed solely at documentation. SEO in documentation is very important as this is how people will find what they're looking for.--Groundup 14:17, 28 January 2011 (EST)
I think I just said not to use conversational style. If you don't like that, you may want to revert it. I don't particularly favor conversational style in documentation. Wikipedia:WP:YOU and all that. On the other hand, the semantic mediawiki documentation reads OK, though it slips back and forth from more formal writing into "you" writing, as in itsand Types documentation --AngelinaBelle 16:01, 28 January 2011 (EST)