We're looking for your comments on how to best organize the wiki's content.
Content structure
The [/index.php?title=Talk:Main_Page&offset=20120409004541&lqt_mustshow=26 highlighted comment] was created in this revision.
The sooner we decide on a content "structure" the better. Now, I know this game is still pre-alpha and info is scarce, but we should still decide on a structure and rather amend it later if need be. We need to ask ourselves:
- What kind of articles will be written?
- What kind of categories will cover these topics?
- How should the category hierarchy look?
- Do we need additional namespaces for certain things (namespaces are the prefixes in some titles, like Template, Project, File, etc)?
- How will categorization be done? Will people have to manually add them, or should they be added to articles with templates?
I don't have much to say about structure, but I do have something to say about tone.
There are two tones that an article can have. For informative articles (such as those reporting factual information such as registers, opcodes, etc), the tone should be descriptive and avoiding idioms such as "you" and "we". However for "tutorials", the writing should engage and involve the reader, since it's designed for guidance. I admit that my articles blur the lines between descriptive and tutorial, so they'll need some refining.
That's a very good point, and perhaps a point in favor of putting tutorials in their own namespace, so that there is no doubt what tone should be used.
I personally don't like namespaces - they seem to be a sloppy way of enforcing categorization when categories work just fine. Namespaces are better reserved for meta-article (articles about the wiki) than articles about 0x10c. That's just me though.
Types of articles should cover three major groups.
- Gameplay
- Programming References
- Tutorials
Gameplay covers game mechanics (the ship and stuff like that). Obviously we should not do anything like this now, since it's all speculation.
--
A programming reference is like a man page. It should have very high level and very fine-grained details about particular aspects of programming in DCPU. These would have the descriptive tone. Consider an article on Video RAM
* high level intro: "Video ram is how you write to the console. * description of features and interface. "It starts at 0x8000 and is 0x180 wide - 32 columns, 12 rowss. Write only". * programming example. piece of code with comments that show how it's done
Descriptive articles would be very short and self-contained, and should be modeled after most programming references.
--
Tutorials are "human-readable" manuals designed to introduce and teach a concept to a reader. These should have a goal in mind "learn how to convert to binary and hex", and should be written in a less standoffish manner than a technical reference. Obviously, these can't afford to be rigid if that gets in the way of the lesson. These have to be written in a friendlier tone to facilitate learning.
* learning objectives - high level description of what you will be teaching the reader * step-by-step tutorial * conclusion
Rather than putting them in separate namespaces, could we use a naming convention like "Tutorial/Beginner's Guide"? I've always liked that setup; it lets you see at a glance that it's a tutorial, but keeps Tutorials in the main namespace.
I think it would be a good idea to put effort into writing style/formatting guidelines in the Help: namespace. I've been meaning to write a Help: Templates, for instance. A Help: Categories might be nice, too.
