Meta/How to Write and Format an Article for TDN
From TDN
|
Goals
Before you put pen to paper (or finger to key), you should take a moment to consider a few key things:
- What are your goals? Where are you going with this article? What are you going to cover? Don't be afraid to leave a few sections for people to fill in later if you have important information to impart. (But don't just leave blanks everywhere, either.)
- What is your audience? Are you trying to target beginner, intermediate, or advanced users? Is this for artists, scripters or coders? It might make sense to indicate at the start of sections what audience you're addressing, or to put different information in different places based on who you're targeting. Hiding art tips in the middle of the code docs may not be very helpful for people. Similarly, code explanations in an art doc might just confuse folks!
- Keep TDN's goals in mind! Clear, factual writing on Torque-related topics.
- When in doubt... Talk to an editor or consult the community. The writing process always benefits from feedback. You can find some on the #TDN IRC channel regularly.
Creating a new article
Don't forget to read How to Choose an Article Title to make sure you're putting your article in the right place. If people can't find it, they won't read it!
Once you've chosen a title, the easiest way to create it is to simply type it into the URL bar. Say you chose the title Meta/How to Write and Format an Article for TDN - just stick the site URL (http://tdn.garagegames.com/wiki/ as of the time of writing) in front of it and open the page with your web browser. In our example you'd point to http://tdn.garagegames.com/wiki/Meta/How to Write and Format an Article for TDN. Or you can create a link to the page from somewhere safe (like your user page, which is linked to from your name at the top of the page) and click that instead.
Once you're at the page, which is most likely blank, you'll need to edit it. On a wiki, new pages are created by simply editing what was blank space. So click the edit link, and you're ready to go. If there's already content there, don't forget to read over it and make sure you make changes that mesh with what was there, rather than simply overwriting it.
Putting content into it
What to put into your article? That's something you yourself best know! There are other articles on the site that give guidelines on writing for specific audiences or for particular content styles, and overviews of style. The Meta page is the best place to find this information.
(Add some more helpful links and tips here -- Ed.)
Care & Feeding of Articles
Don't forget to check up on content you've written or contributed to from time to time. Make sure it's still accurate, and that no typos or formatting snafus have snuck by. Presentation and accuracy is just as important as the basic content, and since Torque is a living changing engine, so should the docs.
Things can always improve! :)
