Wiki style guide proposal

[tactica]

OK, here's a quick proposal while I'm still paying attention

For keyboards, how about this for a framework:

* infobox dkeyboard
* Introduction, with a general overview of the board
* History (optional, mostly for vintage boards)
* What's in the box (optional, mostly for contemporary boards)
* Design and features, mentioning pros and cons
* Variants
* Reception (mentioning how successful the board is/was)
* Gallery
* See also (with pointers for something in the wiki itself)
* External links (for everything else)
* References, using named and grouped references as proposed by 002 in this thread
* Categories, in ascending order of scope ("List of all keyboards" comes last)

For switches and anything else I haven't planned anything yet because I'm still perusing the keyboard pages for obvious problems. Switches will come later.

Also, about style:

* References and external links are in the format "* <Source> - [<URL> <title>] <extra>" where "extra" could be something like "Japanese only" or anything else that's worth mentioning. Example:

Code: Select all

* Wikipedia - [http://www.example.com Review of board blah] (French only)

* Whenever a dead reference or external link is detected and no replacement can be found, they are marked as such by striking the whole content and adding a visible '''(DEAD!)''' notice. Example:

Code: Select all

<del>* BOFH - [http://badbadurl.com It was nice while it lasted]</del> '''(DEAD!)'''

* Sections are specified using the ==Title== format (no spaces between title name and equal signs) with the contents beginning in the line immediately next and separated by a single line from the previous/next section. Example:

Code: Select all

}} <!-- end of infobox -->

==Introduction==
yadda yadda..

==History==
blah blah...

* When mentioning keys on a keyboard, surround them in <code>...</code> tags to make them stand out. This would make key combos easier to follow (?)

[Findecanor]

We already have the rule that when a reference is an external link, the date of retrieval should be noted.
Then it would be easy for the reader to see if the link is old. If a link goes to a dead web page, you could look it up at that date on the Internet Wayback Machine.

[tactica]

Good idea.

Also, of course I forgot the "How to disassemble" section in the proposal, which should be optional and only needed when the operation is basically not idiot proof.

[tactica]

Also a quick mention on the "emdash" someone (zts?) asked about and is used in refs and external links. I agree that emdash looks better than a simple hyphen or minus sign because it is larger, so I'm proposing to use it. On a Windows machine with a full sized keyboard you can enter it using extended mode: just hold down Left Alt and type 0151 in the numeric keypad. Or, you can always use the &mdash; HTML entity.

[zts]

Looks good, I guess, just depends on how much flexibility is allowed ... Some wiki authors have a great deal of knowledge about specific keyboards or switches, etc. and confining them into a template may be a difficult task. Should be some type of balance between the need for consistency/uniformity and non-templated needs. Anywho ...

The gallery should contain the full gallery name:
example -- Gallery: TheBestKB

that allows for additional gallery and/or sub-galleries in the future:

==Gallery: TheBestKB==
==Gallery: TheBestKB Special Edition (SE)==
===Gallery: TheBestKB SE Manufacturing Defects===
===Gallery: TheBestKB SE JIS Layout===
==Gallery: TheBestKB "Batlefielf 17 Edition"==
===Gallery: TheBestKB "Batlefielf 17 Edition" Clone Switches===

BTW, I'd leave KBT/KBC as it is/was -- one of them may get offended if classified under the other. The common ground there is Vortex as the OEM for both.

[tactica]

Looks good, I guess, just depends on how much flexibility is allowed ... Some wiki authors have a great deal of knowledge about specific keyboards or switches, etc. and confining them into a template may be a difficult task. Should be some type of balance between the need for consistency/uniformity and non-templated needs. Anywho ...

Well... Sure, but you have to start at some common ground. I don't mind to clean up after someone else entering the really juicy stuff, but you need a reference to go by.

The gallery should contain the full gallery name:
example -- Gallery: TheBestKB

that allows for additional gallery and/or sub-galleries in the future:

Hmm... You can do the same using separate <gallery ... caption="text"> markup, which IMO looks neater. Just like you don't use several separate sections named somehow the same to refer to different variants since you already have the "Variants" section for that. A single "Gallery" section is IMO cleaner and less prone to confusion.

BTW, I'd leave KBT/KBC as it is/was -- one of them may get offended if classified under the other. The common ground there is Vortex as the OEM for both.

Yeah, I wan't very sure with that edit... OK, I just undid those changes. Thanks

[zts]

^ the other way around this is to check the most prolific DT wiki authors, like beardsmore, 002 and others who have displayed either a great technical knowledge or great documentation skills or both, and see what they have in common in terms of formatting, references, chapters, paragraphs, etc. These people are most likely to get upset about the simplification (dumbing down) process that templating/uniformity often leads to. Balancing the chaos and order without losing DT wiki personality is an art form

[tactica]

Well, you asked for a style guide so you do the research on that I agree that information is more important than uniformity, yet uniformity helps not to miss the details and enhances readability. I have previous experience documenting software so I tend to favour order and standardization over chaos free style.

BTW, any thoughts about moving the plethora of Model F/Model M... boards into separate pages?

[zts]

Well, you asked for a style guide so you do the research on that I agree that information is more important than uniformity, yet uniformity helps not to miss the details and enhances readability. I have previous experience documenting software so I tend to favour order and standardization over chaos free style. ...

Oh, I agree with you, the standardization has huge benefits and can still be flexible enough to accept some deviations from the format. For example:

==Design & Features==
===Early Defective Batch===
===The Version Without the Fn Key===
===Too Slick ABS Keycaps Issue===
===Full Specs===

I mean it could be flexible enough if there is some information important enough to deserve a subheading. "See also" is helpful for additional info. Maybe an optional "free style" section for prolific writers ... something like "additional info".

BTW, any thoughts about moving the plethora of Model F/Model M... boards into separate pages?

Maybe we can extend the discussion in this thread:
http://deskthority.net/wiki-talk-f33/in ... 10478.html
The people (bhtooefr, Mu, seebart, andrewjoy, Ander) there seem to have some thought about the classification and other issues. Pretty sure they can help in regards to the Model F/M. Or a new thread.

[Muirium]

Oh yeah, I've definitely got more thoughts about wiki organisation than I have desire to actually wrangle the damned thing in person.

Um, any chance we could have a… I want to say standard form but I guess I essentially mean a bloody wizard. So clods like us can't screw up the most basic stuff while we dump core in new pages?

[tactica]

Oh, I agree with you, the standardization has huge benefits and can still be flexible enough to accept some deviations from the format. For example:

==Design & Features==
===Early Defective Batch===
===The Version Without the Fn Key===
===Too Slick ABS Keycaps Issue===
===Full Specs===

I mean it could be flexible enough if there is some information important enough to deserve a subheading. "See also" is helpful for additional info. Maybe an optional "free style" section for prolific writers ... something like "additional info".

OK. I'm happy as long as we can agree on the top level headings, so to speak "Trivia" is probably another one worth supporting as default.

BTW, any thoughts about moving the plethora of Model F/Model M... boards into separate pages?

Maybe we can extend the discussion in this thread:
http://deskthority.net/wiki-talk-f33/in ... 10478.html
The people (bhtooefr, Mu, seebart, andrewjoy, Ander) there seem to have some thought about the classification and other issues. Pretty sure they can help in regards to the Model F/M. Or a new thread.

Definitely. And another thread I overlooked in my rush to ask...

[tactica]

Oh yeah, I've definitely got more thoughts about wiki organisation than I have desire to actually wrangle the damned thing in person.

Um, any chance we could have a… I want to say standard form but I guess I essentially mean a bloody wizard. So clods like us can't screw up the most basic stuff while we dump core in new pages?

It's not that difficult. I learned the basics by experimenting, previewing what I was doing before comitting my changes, copying&pasting from other pages... I didn't know a word about wikis until I started editing this one. I've barely began scratching the surface but it's enough to edit anything and add new content in a fluid manner.

Ah come on, you can do it! Besides, we are here to help each other in case of any doubts, and who knows, if you get into real trouble with markup you might receive some wisdom cookie from the Big Brother too

[002]

This is off-topic but tactica, do you have Spanish selected in your wiki language preferences by any chance?
I noticed the other week that the DT twitter wiki bot started tweeting in Spanish and webwit suggested it might be because of this setting

[tactica]

Err... Yes, I do