Wiki manual of style

All about the OSDev Wiki. Discussions about the organization and general structure of articles and how to use the wiki. Request changes here if you don't know how to use the wiki.

Moderators: JAAman, klange, Octocontrabass, sortie, kmcguire, chase, thepowersgang, Owen, Combuster, AJ, 01000101, carbonBased, Candy, pcmattman

User avatar
Combuster
Member
Member
Posts: 9301
Joined: Wed Oct 18, 2006 3:45 am
Freenode IRC: [com]buster
Location: On the balcony, where I can actually keep 1½m distance
Contact:

Post by Combuster »

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: [wiki]Assembly[/wiki] and [wiki]CPUID[/wiki] (i prefer the first style)
"Certainly avoid yourself. He is a newbie and might not realize it. You'll hate his code deeply a few years down the road." - Sortie
[ My OS ] [ VDisk/SFS ]
User avatar
smiddy
Member
Member
Posts: 127
Joined: Sun Oct 24, 2004 11:00 pm
Location: In my cube, like a good leming. ;-)

Post by smiddy »

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: [wiki]Assembly[/wiki] and [wiki]CPUID[/wiki] (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. ;-)
User avatar
chase
Site Admin
Posts: 689
Joined: Wed Oct 20, 2004 10:46 pm
Location: Texas
Contact:

Post by chase »

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
Posts: 6
Joined: Sun Aug 06, 2006 2:19 am

Post by FMota »

Oh my. Well, needless to say, I prefer the first.
Glad to be used as an example. :p
User avatar
Brynet-Inc
Member
Member
Posts: 2426
Joined: Tue Oct 17, 2006 9:29 pm
Freenode IRC: brynet
Location: Canada
Contact:

Post by Brynet-Inc »

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 8)
Image
Twitter: @canadianbryan. Award by smcerm, I stole it. Original was larger.
User avatar
jhawthorn
Member
Member
Posts: 58
Joined: Sun Nov 26, 2006 4:06 pm
Location: Victoria, BC, Canada
Contact:

Post by jhawthorn »

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

I believe that ...
  1. 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.
  2. 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.
  3. 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.
User avatar
Combuster
Member
Member
Posts: 9301
Joined: Wed Oct 18, 2006 3:45 am
Freenode IRC: [com]buster
Location: On the balcony, where I can actually keep 1½m distance
Contact:

Post by Combuster »

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 8) )

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...
"Certainly avoid yourself. He is a newbie and might not realize it. You'll hate his code deeply a few years down the road." - Sortie
[ My OS ] [ VDisk/SFS ]
User avatar
jhawthorn
Member
Member
Posts: 58
Joined: Sun Nov 26, 2006 4:06 pm
Location: Victoria, BC, Canada
Contact:

Post by jhawthorn »

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/
User avatar
Combuster
Member
Member
Posts: 9301
Joined: Wed Oct 18, 2006 3:45 am
Freenode IRC: [com]buster
Location: On the balcony, where I can actually keep 1½m distance
Contact:

Post by Combuster »

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...
"Certainly avoid yourself. He is a newbie and might not realize it. You'll hate his code deeply a few years down the road." - Sortie
[ My OS ] [ VDisk/SFS ]
User avatar
Walling
Member
Member
Posts: 158
Joined: Mon Dec 04, 2006 6:06 am
Location: Berlin, Germany

Post by Walling »

I think the style of article names should be something like this:
  • [wiki]Memory management[/wiki]. Plain article. Space used and no CamelCase.
  • [wiki]Global Descriptor Table[/wiki]. (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.
  • [wiki]CPUID[/wiki]. An article about an assembly instruction. Should IMHO be all uppercase.
  • [wiki]DMA[/wiki]. 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 [wiki]CPUID[/wiki] 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?
User avatar
Combuster
Member
Member
Posts: 9301
Joined: Wed Oct 18, 2006 3:45 am
Freenode IRC: [com]buster
Location: On the balcony, where I can actually keep 1½m distance
Contact:

Post by Combuster »

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)
"Certainly avoid yourself. He is a newbie and might not realize it. You'll hate his code deeply a few years down the road." - Sortie
[ My OS ] [ VDisk/SFS ]
User avatar
Candy
Member
Member
Posts: 3882
Joined: Tue Oct 17, 2006 11:33 pm
Location: Eindhoven
Contact:

Post by Candy »

bcat wrote:/me agrees.

DownWithCamelCase! :lol:


That just reminds me of the "Verein zur Behalt von dem Genitiv".
User avatar
chase
Site Admin
Posts: 689
Joined: Wed Oct 20, 2004 10:46 pm
Location: Texas
Contact:

Post by chase »

Candy wrote:
bcat wrote:/me agrees.

DownWithCamelCase! :lol:


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.
Post Reply