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=20120414124536&lqt_mustshow=81 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 personally think namespaces and categories work great when together.
The problem with namespaces is when a contributor adds something to the article, they aren't familiar with the namespaces of the wiki. So we (as editors) have to move the article and set redirect links to clean up after them. However, when a user fails to add an article to the appropriate namespace, we just add the category.
It just feels like enforcing strict organization like this is making more work for us. We want a low barrier to entry for contributors, and we also want our cleanup jobs to be as streamlined as possible. Enforcing article name conventions, especially for tutorials, seems counter-intuitive.
Also, the colons in the titles of the pages look ugly. But maybe I'm the only one who thinks so. :P
For me, wikis just don't work without namespaces. It's just all technical and all. Helps you from being confused with actual articles.
Cronos Dage • talk • contribsMy sentiments on the matter are very well expressed in this Youtube video.
Sounds like a good way to fit the articles into different categories.
But what about article series? Of course you can write one long article to show newbies what assembly language is like, but if you really want to teach people how assembly language (even on the DCPU-16) works, you need several chapters.
Therefore I suggest that we organize the tutorials section in such a way that people can either create an article series or standalone articles. And then we should distinguish between newbie-friendly tutorial-articles and more advanced stuff. If you are really new to assembly programming you will have a hard time telling if you are too dumb to understand this stuff or if you just haven't seen the right tutorials yet.
In-depth assembly language tutorials are the only thing I can think of at the moment that would justify an article series. But maybe there are other things that need greater explanation efforts?
I agree wholeheartedly. I've been writing standalone articles so far, and it's my hope that we can have an overarching "syllabus" that connects them together and glues them into a full tutorial.
I figure maybe we have a template for advanced tutorials that does something like:
"This article covers an advanced programming topic" "You should understand **prerequisites** before reading this article"
And the prerequisites can clearly point out what should be known in the first place.
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.
I have a proposal for Help:Style guide. Since that page only had "Coming soon" on it, I just added my proposed content directly to it, but please consider it only to be a proposal for now.
Seeking discussion.
Well, it seems well-organized. Good work. We might also, like many other things, import from other wikis such as the English Wikipedia or wiki.tf2.com. (click links for respective style guides)
Cronos Dage • talk • contribsWhile much of the discussion is good, one question I'd like to understand better what is this wiki being used for. From the articles present, it documents what little we know about the game so far - largely the DCPU specifications. Tutorials have a place as well. However, is it appropriate to use the wiki to specific suggested design requirements? I've given some thought to conceptual requirements for a ship, parameters of the universe (like how to navigate in it), physical movement, etc. from a *design perspective*.
Personally, I would think that the wiki is a good place for such things, but given the kind of wild speculation I've seen on the forums, it might be difficult to control. However, with proper curation, I think that design input would greatly help Notch (etc) move forward with game development. The alternative is to post suggestions to the forum, where it will be embedded in background noise.
- Mark
Wikis, in general, serve as authorities of "the way things are". Its a way of crowdsourcing documentation, and it works pretty well in general. In the case of games, it even serves as an instruction manual by players, for players.
It's not my place to say what Notch will and will not read. But I don't think we should try to turn the wiki into another source of information vying for his attention for two reasons:
One, if we give way and allow the wiki to contain proposals, conflicting proposals will give rise to edit wars which will end up ruining the reputation of the wiki community. A wiki should NEVER be competitive, and trying to manage this rabidly enthusiastic fanbase is a bad idea. It's going to lead to heavy-handed arbitrary rules, and it'll set a bad precedent for our management.
Two, this wiki has a job to do in the community already. To document 0x10c. We are different from the forums because we make it a point to keep speculation to a minimum. We should not favor any particular fan's pet theory about how the game should be run. Even if we lose favor for not being adventurous, we can establish the place of the wiki as an authoritative place for non-biased facts and helpful tutorials for the game.
I'm not disagreeing to be contrary, and I have no intention of going on a rampage erasing anything I see that looks like proposals to Notch. But I'll fill this forum with my disagreement until the heat death of the universe, as is my prerogative. :P
I'd love to discuss this at length in IRC, so please feel free to ping me in #0x10cwiki or any of the other channels.
