We're looking for your comments on how to best organize the wiki's content.
Content structure
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.
