Tutorial/manual for 1.1?

Subbing

I've been working on a new manual for v1.1. 

Any way we can help with it? Probably during the Beta of 1.1, I'd be willing to review stuff / make suggestions /etc (and I am fairly sure many more people here would be willing as well).

Will it be a new, comprehensive manual covering everything?  Or is it just for new additions to 1.1?

Updating the wiki with the changes and keeping it maintained is probably the most useful thing the community can do for game documentation.  A comprehensive, well maintained wiki > than any native documentation.

Better still would be an official wiki maintained by devs, Stardock editorial types, and perhaps a select handful of volunteers.

Unofficial wikis are OK, but it's always better to have original sources and some login restraints to prevent things like Stephen Colbert fans rescuing the African elephants by changing their population numbers on Wikipedia.

I really don't think a game info wiki calls for as much scrutiny as a global wiki that's used by many millions of people

I never had a problem with the community maintained Gal Civ wiki when it was up to date. It was a much richer source of information than any of the official sources of documentation, detailing not only the game concepts, but in depth analysis of the game mechanics. (Obviously, the devs need to expose these things first, before the community can document them).

It would be nice to see a *lot* of things from the devs.  But they are a small team, with a finite amount of time. At this point, anything that is not  related to working directly on the game, I'm willing to let slide.  Community maintained wiki's for games and software often  grow to be more comprehensive than any official documentation produced by the developers, anyways. 

But that's beside the point.  The guy asked what he could do. Probably not a whole lot to help Brad write the new manual. But the wiki needs love, and people will be referring to a good game wiki long after the manual has outlived it's usefulness.

I. also, would be happy to assist...

OK, I admit I'm on a sort of pedagogical/self-serving-user mission here. On the first mutilated quote: I used the GC2 wiki often when I still had plenty to learn about the game, but I have not lost my opinion that a major weakness of the game was that it lacked serious, clearly authoritative documentation. It's a moving-target problem that can't really be handled with print manuals and needs at least a constantly updated PDF, and would be awesome with both a 'living' PDF and a wiki based on Stardock input and editing.

On the second chunk: It's an esoteric point, but I've followed and worked with a variety of software projects and I'm utterly convinced that requiring dev teams to participate in formal documentation will improve both internal communication and communication with outsiders like customers, management, and PR types. Translating between the machine syntax- and human jargon-based world of software creation and plain language is not easy. Constant practice helps software people be more confident that they haven't buried an important idea in obscure (or too-new) jargon, or worse, made a seriously mistaken assumption about their listener/reader's assumptions--and that applies both when talking amongst themselves and talking to outsiders.

[edit]

Never mind. I decided this is sort of not worth arguing about.   Carry on .

I already did...

And I peeked at your edited reply. Don't think we're really arguing so much as venting with different emphases. My only real problem with an all-volunteer game wiki is that it has the same fundamental weakness as Wikipedia: you need to take all the info with a grain of salt. I use Wikipedia almost every day, but I never forget that Stephen Colbert fans helped 'save' the African elephant by tweaking its population numbers...

The real woe is indeed long-term and widespread. The software industry as a whole is steadily more documentation-averse. I suspect that addiction to PowerPoint is part of the problem...

I really don't think the liberals/conservatives/democrats/republicans/libertarians/Jews/Muslims/Mormons/illegal aliens/terrorists/socialists/Catholic priests/ Gypsies /anchor babies (insert personally applicable ideological boogeyman du jour) have an agenda for misrepresenting the attack speed of a longsword in Elemental.  You keep bringing that point up, but I think we can safely focus our discussion on the scope of the sort of game wiki's involved, which are no more likely to suffer mischief than any other random site on the web.  They're simply not big or important enough, nor do they deal with issues contentious enough to solicit such hijinks.

And again, you keep making these statements indicating you think community wikis are somehow inferior efforts. All evidence to the contrary. Game community wiki's frequently exceed expectations, and are far more accurate and in-depth than any third party game guide you could purchase.  A developer is just as likely to make an error in a closed wiki as a community member in an open one, assuming they are documenting the same information...except an open community wiki will be subject to more editorial scrutiny and more quickly corrected. There is simply no evidence, in my experience, to support your position on the sort of wikis that are germane to this discussion. I'm sorry you had a bad experience on Wikipedia proper, but it doesn't really apply here.

The only real difference between community wiki's and developer wikis, is that the former actually exists, often thrive, and are within our power as a community to effect, whereas the latter is mostly wishful thinking.

And once again, to sum up to any third party thinking of jumping on me for saying "Wiki's are better than manuals", please understand that is not what I'm saying at all (even though it's often true). A community wiki doesn't alleviate the desire for Developers to reasonably document their games (if the developers don't document the way the game works sufficiently, you can't magically do so in a wiki, at least until some enterprising player reverse engineers the game and documents it), not to mention portability preferences.  Somebody asked how they can help with documentation...beyond post release error reporting, you can't really help Brad write the manual or write it faster...but the Elemental Wiki is within your power to help with, and will need updating with the new game version.   I simply got sucked up in discussing some of G.W.'s anti-wiki rants and conspiracy theories.

One of the best reasons to take up constructive arguments as a hobby is that they can help you get a decent grip on your own thinking. You're half (or more) right about me heckling 'community' game wikis, or at least coming off that way because I'm not yet able to nail down my own complaint well enough. What I think I'm really griping about is not that public wikis are worthless (I don't believe that at all). It's that dev crews without a strong habit of semi-formal and/or formal writing are not being all they could be. Living and thinking in code and PowerPoint bullets is not enough; good art and effective understanding require prose at minimum, and perhaps a tad of poetry (although I'm crap for reading or writing that stuff).

Plus I probably have some crossover from my deep and abiding fear of seeing all TBS games descend into a Let Them Eat Mods morass that leaves folks who just want to buy a good game and play it out in the cold.

I think you have sort of a vague stew of tengential anxieties that may be valid and important points to raise in discussions elsewhere, in other contexts.  I don't think there's any evidence to support them applying anywhere in this discussion, or at least at the point in which they were inserted into the thread.

  I think literacy and formal writing skills are beneficial for everyone to have, but game developers have made plenty of excellent games without demonstrating such, and there are far better reasons to want timely and reasonable game documentation without worrying about how their penchant for writing wiki entries is going to affect your game quality.  And it still has nothing to do with the Dev's ability to contribute to a community wiki if they have the time or inclination...some game devs do. An open wiki is open for everyone.

  You lost me at the poetry thing though...I think that's sort of going off the rails a bit for the discussion at hand about game documentation and community wikis, and we've now begun a slow descent into madness.   It seems as good a place as any for me to run screaming from this thread, and never look back.

Cheers!

Even with the best intentions, the one knowing the game inside-out never explains the right things. =P

To a certain degree I can agree but in other ways i have to disagree the one who knows the game inside out maybe the only who can explain somethings....

From a technical writing standpoint each has its merits. A Subject Matter Expert (SME) knows the actual inner workings, but is so familiar with the topic that they often miss details that seem obvious to them. A complete outsider on the other hand can easily approach the topic as a new user, but can end up misinterpreting some of the systems without direct knowledge of what is really happening. In a perfect world all manuals would be written by an outside technical writer who was hired to work in tandem with the game's developers throughout the final testing phases.

There was some talk a while back from Stardock folks about them hiring dedicated editorial talent, but I don't know if that got abandoned or transformed into the deal with Random House. I know times are tough for anyone making a payroll these days, but I sure hope that eventually they make another try at doing exactly what you describe.

p.s. I'd amend your quote a tad to have the editorial talent do some preliminary work (very rough outlines, moving-target glossaries) linked to major project milestones from the beginning.

See some of Brad's modding "tutorials" for examples of this.