Allegwiki
So, I'm supposed to be making sure all of the documentation is OK. Here are some groundrules I'll make for this forum of mine.
- Technical documentation only should be discussed here, with the exception of a small handful of the most commonly-asked gameplay questions that are covered in the KB.
- Gameplay documentation is handled by the Academy, Training, and others. Not us.
- NOTHING should be published to "public locations" unless it's been reviewed by at least 2 Documentation Mods and both agree that there are no typos/mistakes/misinformation
- Everyone should feel free to propose suggestions to reword any documentation. Just post a topic here, or reply if a topic is already discussing the article you'd like to improve.
- Doc mods should feel free to post drafts in this forum, or any other "hidden" documentation they're preparing on the side. The more eyes the better. (Just make sure you have another mod sign off before publishing!)
- Write your documentation for the idiot. Sorry if that's not politically correct, but try to make your solutions understandable by 8 year olds. If you need to add technical stuff to explain it, try to organize your solution so that you give the basics of the problem/solution up top, and a disclaimer "For more detailed/technical information, see below".
- Follow similar form across documents where possible. (Don't freak out if yours is slightly different. Fix it if you have time, or leave it.) See below for an example
- Stay Classy
Enjoy documenting!!
--TE
Subject: Try to include the exact error text seen by the user in the subject. eg: "How do I fix 'Cannot connect to lobby'?"
- At the top, include the question or error text at the top of the article so users know where they are. A good start is: "This solution covers the following error messages..."
- Underneath, include symptoms or other specific info that uniquely identifies the issue/problem. This is important because there could be 2 or more ways for a user to receive the same error text/problem. "Do you see 'Could not connect to Lobby' when clicking 'Free Games Listing'? Or do you see that error message in the middle of gameplay after being kicked out?"
A good example is: "You receive the error 'blahblahblah' when clicking yaddayadda after you did suchandsuch"
- (this isn't necessary but depending on problem can help) Identify the cause of the problem in a small sentence/paragraph. eg: "This problem is encountered when Allegiance cannot talk to the server; something is likely blocking it"
- Solution. This should list specific steps (as exact as possible) on how to resolve the symptoms read at the top of the article.
- Separate multiple solutions visually. Paragraphs with bold headlines clearly separate one section of a solution from another
- bullet points separate steps visually too
- The solution is dependant on what's being fixed, so there's leeway here. Just make sure you cover the bases and lay out the solution in clear/easy wording (Not too technical!) and visually separate the solution from the rest of the document. Most users dart their eyes straight to a set of itemized instructions on how to fix it instead of reading your whole article. Don't be sad - it's not because of your writing.
- format your stuff nicer than this example. I'm lazy today and didn't watch my capitals, bolds, italics, etc.
- Additional Information should be separated below the solution under its own heading. Put technical stuff here for the people who want to know specifics
- Always include a link to the helpline somewhere in the article with text like "If this didn't solve your problem, go here and post a new topic"
- Feel free to be lazy and copy/paste sections to your new articles - it'll help keep everything consistent. Just make sure you proofread what you've copied!!!!!!!11
In everything you write, try to visually separate important strings from your text. Ideally all filepaths, registry keys, and other technical strings should be in Courier New, or other monospaced font to distinguish it from text. Otherwise users may not know whether you're talking about different program files like word and excel or the program files folder. See what I did there? Annoying, ain't it?
Make it stand out. (If you can't do fonts, do bold/italics/underlines/colours/whatever is at your disposal. Don't overdo the color though)
OK that's good enough.
Obviously everything can't be covered identically so use your judgement as best you can... but we should make an effort to keep things in a consistant format. If you think anything about this format sucks, propose improvements. Documentation is always changing, and if you can make it better, let's hear it!!
--TE
DUDES!
Stop duplicating the Academy.
The Academy has been the place to visit to learn how to play the game for years. That hasn't changed.
Try to keep the wiki concerned with technical problems/resolutions, how to set up a server, how to connect your server to the public lobby (who to contact and what to provide them with [IP address!]), how to connect to the beta lobby... etc etc.
Pretty much anything gameplay related (except for first-visit type info) should be linked to the Academy.
--TE
