Wiki manual of style

Combuster · Post by **Combuster** » Sat Dec 02, 2006 6:47 am

Is there some manual of style? the notation of code blocks has gotten inconsistent and we better choose a style before we have to change half a wiki to a different style
For comparison: Assembly and CPUID (i prefer the first style)

smiddy · Post by **smiddy** » Sat Dec 02, 2006 8:44 am

Combuster wrote:Is there some manual of style? the notation of code blocks has gotten inconsistent and we better choose a style before we have to change half a wiki to a different style
For comparison: Assembly and CPUID (i prefer the first style)

Either style is OK with me, they're both readable, the content could use some help, but that is an entirely different story.

chase · Post by **chase** » Sat Dec 02, 2006 5:46 pm

I like the 2nd because you can title each code block but it requires extra markup and Wikipedia uses the first so for those reasons I think we should use the first. We should probably add a Style section to [wiki]OSDevWiki:Editing[/wiki]

Edit: I think space in title names are fine where they are needed but why not just name the page A20?

FMota · Post by **FMota** » Sat Dec 02, 2006 6:42 pm

Oh my. Well, needless to say, I prefer the first.
Glad to be used as an example. :p

Brynet-Inc · Post by **Brynet-Inc** » Sat Dec 02, 2006 8:16 pm

FMota wrote:Oh my. Well, needless to say, I prefer the first.
Glad to be used as an example. :p

Me too lol, I'm the one who added the Contents Box look to the Assembly article..

I thought it looked neat

jhawthorn · Post by **jhawthorn** » Sun Dec 03, 2006 3:35 am

NB: I am the author of the page and template used in the second example. Bias will likely be exerted.

I believe that ...

Both styles need to be employed. Though the first style looks great and is easy to edit when only a few lines of code are involved, many (or at least I) find the code slightly hard to read when there isn't enough of a border between it and other text.
Both styles need to use templates. Is has already been noted that setting a certain style now would provide a lot of tedious work if a different style was desired in the future. Templates, however, would allow editing a single page (ATM template:Code) to change the style for the entire wiki. Templates also allow for other neat features.
If not completely removed template:Code needs to be fixed. Eugh! Look at that thing! Blue on grey! I was actually waiting for some style to develop before fixing the template. Hopefully we can establish a solution in this thread.

P.S. On an unrelated note could chase `chmod +w /var/httpd/www.osdev.org/mediawiki/images`, the image uploader is broken.

Combuster · Post by **Combuster** » Sun Dec 03, 2006 9:28 am

jhawthorn wrote: Both styles need to be employed. Though the first style looks great and is easy to edit when only a few lines of code are involved, many (or at least I) find the code slightly hard to read when there isn't enough of a border between it and other text.

Current code snippets are already contained in a box with a different background color, and the only real difference is that you added a header to it. (invitiation for criticism

)

If not completely removed template:Code needs to be fixed. Eugh! Look at that thing! Blue on grey! I was actually waiting for some style to develop before fixing the template. Hopefully we can establish a solution in this thread.

Suggestion: Since the majority prefers wiki's built-in style (maybe due to familiarity), could you change the template to look like the built-in style, but with header?

Still, if you want you can advertise some alternative templates, maybe you'll be lucky and we like it

Both styles need to use templates. Is has already been noted that setting a certain style now would provide a lot of tedious work if a different style was desired in the future. Templates, however, would allow editing a single page (ATM template:Code) to change the style for the entire wiki. Templates also allow for other neat features.

If you provide a template:Snippet, i'm fine with it. I dont suppose chase wants to change the builtin wiki styles manually...

jhawthorn · Post by **jhawthorn** » Sun Dec 03, 2006 2:27 pm

I have changed Style 2 to Style 1 via the template (including removing the header). If I create any more bearable templates for code I will make a post here before moving it into the main namespace.

While we're on the subject of style could I get some critiques on these SVGs I quickly made for the wiki? (Rendered as PNGs)

http://s138.photobucket.com/albums/q264 ... orn/osdev/

Combuster · Post by **Combuster** » Sun Dec 03, 2006 4:10 pm

Saw those images earlier on the wiki - Nice work.

i have some remarks about the contents though (micro/exokernel img)... ill be posting it on the wiki talkback pages shortly as its not really about style...

Walling · Post by **Walling** » Thu Dec 07, 2006 3:28 pm

I think the style of article names should be something like this:

Memory management. Plain article. Space used and no CamelCase.
Global Descriptor Table. (just created that one) The name is often referred to as GDT. When articles are often referred by their abbreviation or is a techical term I think CamelCase can be justified. But a redirect should be created from Global descriptor table, and in this case GDT as well. This is to catch links from other articles and user searches.
CPUID. An article about an assembly instruction. Should IMHO be all uppercase.
DMA. An article with an abbreviation as name. Should be all uppercase. Should however redirect to the article named Direct Memory Access in my opinion.

Further all articles should start by shortly introducing the subject, like the CPUID article.

It is a big job, but I'm not saying that articles should comply right now. It should only be some guidelines to follow when creating and editing pages. In time the wiki will have a more consistent style.

What do you think?

Combuster · Post by **Combuster** » Thu Dec 07, 2006 5:59 pm

Naming convention:
Agreed (I've been doing this all along so...)
Introduction:
Lot of work. Generally requires reorganizing/rewriting the page. Haven't done it for all pages.
However, some close-to-stub-like-pages dont need it - like several of the various file systems (they also easily fit into the screen). Still its pretty annoying to convert FAQ style of ordering to Wiki style of ordering. I'll try to do this from now on, but dont blame me if i miss it sometimes.
Redirects:
I preferrably use the common name, short or not. If you want a extra redirect, be my guest, but i doubt people looking up Interrupt Descriptor Table instead of IDT.
As a sidenote, is it useful to put all abbreviations in an separate catergory? - Gives people a lookup page automagically.
CamelCase:
since mediawiki suppports spaces properly, i think we can ban it. (ALL CAPS is a different story)

Candy · Post by **Candy** » Fri Dec 08, 2006 12:00 pm

bcat wrote:/me agrees.

DownWithCamelCase!

That just reminds me of the "Verein zur Behalt von dem Genitiv".

chase · Post by **chase** » Fri Dec 08, 2006 4:19 pm

Candy wrote:
bcat wrote:/me agrees.

DownWithCamelCase!
That just reminds me of the "Verein zur Behalt von dem Genitiv".

Guess it loses something in babelfish translation...

But yeah, CamelCase sucks. One of the reasons I picked mediawiki.