Register
handmade.network»Wiki»Wiki/Editorial Guide
#13924 nakst Jan. 6, 2018, 11 p.m.

A discussion, copy-pasted from the HMN Discord, started by eisbehr's enquiries into the "3rd person" rule.

chronal - Today at 20:21 @eisbehr it's standard practice with descriptive content. for tutorials it might make more sense to use "you", but "I" is still kinda weird as wiki articles are collaborative works and there will usually not be one single author

zhiayang - Today at 20:22 don't you usually include the voice in your head as your partner when having discussions with... your second head-voice-person-thing?

eisbehr - Today at 20:22 Maybe I'll use "the immaterial cloud of authors decrees" :stuckouttongue: I'll see what I can do.

d7 - Today at 20:23 the question to ask is if this will really be a wiki or more of a collection of tutorials from different people

nakst - Today at 20:23 imo it's fine for tutorials to contain I/you, but classic wiki content shouldn't

demetrispanos - Today at 20:24 I agree with @d7, I'm not sure that something like a tutorial makes much sense without an author

hayai -s - Today at 20:26 idk if tutorials are even super useful to people compared to just information about things :x

d7 - Today at 20:26 the line between those two can be blurry

eisbehr - Today at 20:26 Both are useful for different people at different times

d7 - Today at 20:27 especially if the body of information as a whole isn't super rigidly structured. which it already doesn't seem to be.

hayai -s - Today at 20:28 ya... like the thing on the wiki already about keyboard input might be considered a tutorial but is mostly just information about how keyboard inputs work on windows x.X

demetrispanos - Today at 20:28 I think the essence of a tutorial is that it's an edited subset of information with an intended linear experience it's not an infodump

hayai -s - Today at 20:29 i think i'm more thinking about a specific kind of tutorial as being bad instead of tutorials as a thing actually, derp

d7 - Today at 20:29 as a footnote, i used the word "tutorial" loosely in my original comment there to also include "thematic collections of useful information intended for a particular use case"

eisbehr - Today at 20:30 hmm, I guess it's pretty blurry if you look at it broadly. like the typical "here's how you do this one weird trick" blog post(edited)

d7 - Today at 20:31 right

demetrispanos - Today at 20:32 yeah, interpreting it broadly I agree that a wiki can be a reasonable vehicle for a portion of "tutorials"

d7 - Today at 20:32 i meant it the opposite way, though :smiley: that this might not really be a wiki and thus not necessarily require wiki rules and guidelines

demetrispanos - Today at 20:33 aha, always with the sneaky angle @d7

d7 - Today at 20:33 more of a "library of useful resources"

eisbehr - Today at 20:33 It's at least questionable if the wiki is a reasonable place for tutorial type content. And if it makes more sense to wikify the content in the tutorials

hayai -s - Today at 20:35 wiki makes it easier for lots of people to contribute content and keeps everything relatively organized and in one place, at least moreso than a forum or shared blog or whatever so i think it's reasonable place for tutorial kinda stuff at least x.x

eisbehr - Today at 20:36 Like the xlib thing could be more of an exposition of the structure and concepts instead of the guided tour that the tutorial is.

d7 - Today at 20:36 there's a difference between a library where anyone can submit content and a wiki where every article is a collaborative effort with potentially many authors (and a stricter structural format)

hayai -s - Today at 20:37 about how much original author cares about other people editing/contributing to their articles?

d7 - Today at 20:38 not just how much the author cares, but how well the original article lends itself to that kind of incremental tinkering by others tutorials are not just "objective" collections of dry information(edited)

demetrispanos - Today at 20:39 that and also the extent to which the article is necessarily opinionated vs objective/reference "An easy way to learn GL" bakes in lots of value judgements that need not be shared so the idea of randos coming by and editing that, without sharing those value judgements, seems tricky

eisbehr - Today at 20:40 Makes sense

demetrispanos - Today at 20:45 I think with something like wikipedia, you're actually hoping for authorship/voice to dilute to zero whereas with educational material it's usually the opposite

nakst - Today at 20:48 Regardless, getting the tutorials/information out to people is more important than worrying about the tone of the article; that can always be changed afterwards

demetrispanos - Today at 20:48 this isn't just about tone if I want to write a GL tutorial that says "forget about fixed function it's a waste of your life" then someone else may disagree with that

nakst - Today at 20:49 Maybe each user should have their own wiki for scratch articles/tutorials And then if the community likes them they can be copied over into the main wiki

d7 - Today at 20:49 i think i would personally find a go-to place for targeted, hands-on tutorials and case studies of specific problems more valuable than a wikipedia for generic computer terms and patterns (like "virtual memory")

nakst - Today at 20:50 ^^ this is a good point, I felt very restricted trying to write the virtual memory article in a completely generic way I might go back and add examples for a specific architecture, who knows

Kknewkles - Today at 20:51 @abner here's a brilliant idea I had about something else, while thinking of wiki

d7 - Today at 20:51 there's already a wiki for generic terms. wikipedia.

Kknewkles - Today at 20:52 community writing functions for standard stuff, like "generate a matrix" "print a binary representation" "something else useful that people need from time to time" but it's COMPETITIVE TIS/SZIO/OM STYLE speed, memory, parallelization etc TRALALA(edited) so that with time some kind of a community library is born chat, go :duck:(edited) we could call this thing "Mmozeiko is #1 everywhere"

d7 - Today at 20:54 even just from observing this chat, i see so many of the same questions being repeated by people going through the same learning process (for example batching in opengl)

Kknewkles - Today at 20:54 YEAH that's what I was thinking about community giving definitive answers to questions that everyone encounters at some point

d7 - Today at 20:55 instead of reading about the term "batching", a more useful resource would be a practical how-to explaining - and showing with specific examples - why and what. aka a tutorial.(edited)

nakst - Today at 20:55 I agree with d7(edited)

Kknewkles - Today at 20:56 I'll just scrape that, sorry guys. :rofl:

demetrispanos - Today at 20:59 I do think there's a general lack of "here are the N steps to accomplish your first Y" that punt on talking much about concepts and background

demetrispanos - Today at 21:00 especially when you're new to something, just getting the ball rolling at all is often the most costly step "hmm ok I copy/pasted the N steps and now I've batched a bunch of stuff, but it wasn't the stuff I wanted... let me tinker with it until it does what I actually want now"

Kknewkles - Today at 21:02 also a wiki full of tutorials(some major term collision here) is more in the spirit of practical, not theoretical programming also, a strong opinion: any or absolute most of programming articles are useless, pointless even, without some source.(edited)

nakst - Today at 21:02 But, also having our own glossary can't hurt

d7 - Today at 21:02 speaking of @nakst, i'd much rather read a breakdown of his experience of making an os, the goals, the considerations, the traps, the mistakes, the fixes etc than being explained in a general way what an os is, for example

Kknewkles - Today at 21:03 because you can read that crap most anywhere

d7 - Today at 21:03 the more practical and hands-on, the better imo

Kknewkles - Today at 21:03 but Nakst's path of making his own OS can be traced and understood

nakst - Today at 21:03 Maybe I should make a blog, aha?(edited)

d7 - Today at 21:03 as long as the topics are relevant for the audience

Kknewkles - Today at 21:03 probably that's what the wiki should be, a hub of blogs

eisbehr - Today at 21:04 We certainly don't want to copy wikipedia articles, but wiki style articles for specific details do make sense. Like real world implementation details.

Kknewkles - Today at 21:04 "here's the dude I'm reading for OS programming. Now there's that gentleman that's coding the future of coding and then some graphics algos on the side" "now there's that good ol chap that has all the math in the world in the service of getting shit done"

d7 - Today at 21:04 that was kind of my initial point. that it might not be - or have to be - a wiki proper

nakst - Today at 21:04 (also, here's the list of things other people want on the wiki https://handmade.network/blog/p/2765-%5Bnews%5D_what_do_*you*_want_to_see_on_the_wiki)

d7 - Today at 21:05 i think that teaching by example is useful here (again, in reference to the how-to format). by providing a real-world context that gives practical insights - and that allows readers to extrapolate to their own particular use cases(edited) having a repository of more traditional reference materials on the side is fine, of course (i wouldn't mind a section for winapi clarifications for where msdn is either vague, misleading or plain wrong, for example. stuff that isn't readily available in consumable form elsewhere)(edited)

Kknewkles - Today at 21:08 or some DX stuffs that you had to scout for yourself, while the official materials had nothing to say about them

d7 - Today at 21:09 right. in fact, i think i like the GPU Gems series in terms of format. something like that, but more general in topic.

Kknewkles - Today at 21:09 or that thing you told me that one time: d7: if you ever want to "open file location" from code, this is all there is to it if (ITEMIDLIST* pidl = ILCreateFromPath(path)) { SHOpenFolderAndSelectItems(pidl, 0, nullptr, 0); ILFree(pidl); } which I saved to a folder called "recipes" :wink:

d7 - Today at 21:10 yeah. stuff like that, too. an index of how to do <very specific task that some might not know where to look for>(edited)

eisbehr - Today at 21:11 However, Handmade Network will display a sitewide wiki, and we'd like suggestions on what to have shortly after release. Here are some examples already given and mentioned on Patreon: (1) documenting API irregularities in MSDN, (2) central list of OpenGL bugs, (3) detailed schematics (think IP / TCP) and sample implementations of protocols, etc.

Kknewkles - Today at 21:12 (3) OoO

d7 - Today at 21:13 yeah, a place to document api irregularities has been discussed by people here, myself included, for years(edited) so i know. but then we're back to the question of whether it's really a wiki proper, if half the content isn't in wiki form anyway. this all in reference to the "do we really have to avoid using i and me" issue raised earlier if forced to write in wiki form, perhaps a lot of good content won't be written(edited) (or not written in an optimal way)

Kknewkles - Today at 21:16 enforcing a format sounds oopy to me, now that I think about it the question should be "does this article, in whatever for, answer the question is posits - how to draw an image using DX11" then maybe some style changes or whatnots could be suggested

nakst - Today at 21:18 I think this currently theoretical discussion would be a lot better once people actually have started to write some actual articles, then we can decide what we like/dislike

d7 - Today at 21:18 i notice on the site that some of the entries are prefixed with "tutorial" (and they certainly don't avoid using i, like mmozeiko's classic no-crt article) so perhaps the wiki will be more of a supporting lookup service, like the examples 1-3 @eisbehr quoted up there, and the real meat is contained in articles and blog posts and tutorials as "associated material" but not part of the wiki as such iono @nakst i certainly wouldn't like writing an article that turned out to be unfit due to overly rigid and perhaps undesirable formal requirements and then have to either redo it or scrap it

nakst - Today at 21:21 I mean, just write the article however you feel is best Then we'll have a variety of different article styles from different people Giving us insight into what actually works on the wiki

d7 - Today at 21:21 then why the formal requirements now?(edited) this is what the discussion was about

eisbehr - Today at 21:22 I'll try and make my tutorial into "not a tutorial" for the wiki and see what happens.

nakst - Today at 21:22 @d7 I agree, the wiki is too young to have requirements like that

d7 - Today at 21:23 "write the usage code first"

eisbehr - Today at 21:24 I think so far every article on the wiki is written as a 1st person tutorial

d7 - Today at 21:26 imagine if this was to be submitted to the wiki project https://fgiesen.wordpress.com/2011/07/09/a-trip-through-the-graphics-pipeline-2011-index/

nakst - Today at 21:27 and since it's public domain, we could

d7 - Today at 21:27 but it would have to be completely rewritten for no apparent reason except "sounding more like a wiki that way"

nakst - Today at 21:28 I think I should at this point also talk about my experience with the osdev wiki Most articles on it are written in a tutorial-like fashion

d7 - Today at 21:29 osdev wiki is a wiki somewhere?

nakst - Today at 21:29 And that's usually good because of the sample code you get But it does seem to encourage laziness, and errors in the article So you have to cross-reference with a specification most of the time anyway

eisbehr - Today at 21:30 http://wiki.osdev.org/

nakst - Today at 21:30 ...basically meaning I think there needs to be a good middle ground we find between tutorials and reference material

d7 - Today at 21:31 i don't think tutorial-like in any way implies that one should allow lax factual quality requirements

d7 - Today at 21:31 or that the community cannot comment and ask for clarifications, suggest improvements etc(edited)

eisbehr - Today at 21:31 http://wiki.osdev.org/I_Cant_Get_Interrupts_Working

d7 - Today at 21:43 note that i don't have anything against the wiki format per se. it's just that i suspect the hmn wiki is bound to be super sparse (given the breadth of topics it's likely to host, as opposed to something specific to, say, a particular framework or task) , to the point where the wikiness of it ends up being so watered down one might instead have a more free-form index of relevant writeups.(edited) https://developer.nvidia.com/gpugems/GPUGems/gpugems_pref02.html

#13925 Oswald_Hurlem Jan. 6, 2018, 11:07 p.m.

"d7: it's just that i suspect the hmn wiki is bound to be super sparse (given the breadth of topics it's likely to host, as opposed to something specific to, say, a particular framework or task) , to the point where the wikiness of it ends up being so watered down one might instead have a more free-form index of relevant writeups."

Along these same lines I think an unplanned punkish hypertext like c2.com might be what we should aspire to.


Edited by Oswald Hurlem on Jan. 6, 2018, 11:07 p.m.
#13926 abnercoimbre Jan. 6, 2018, 11:41 p.m.

Given these conversations, I've added a Wiki Content paragraph giving people more freedom on what to write and how to present the content. The focus for me right now is to get a bunch of quality content in the first place.


Edited by Abner Coimbre on Jan. 6, 2018, 11:42 p.m. Reason: Add another sentence.
#14051 mrmixer Jan. 21, 2018, 5:01 p.m.

Is there a page somewhere that explains the whole markdown syntax ? Is it possible to use something else then "back quote" ( ` ) for code because it's not an easy key to use on my layout (AltGr + Shift + è) and I'll probably have to search for the combination every times.

#14144 nicoco Jan. 27, 2018, 7:01 a.m.

What about url convension? I think it should have it's entry.

#14320 JasonKnight Feb. 20, 2018, 9:05 p.m.

Hi, I am kind of new here, but I thought I would try my hand at helping out with the Wiki, as that seems to be something I can do acceptably well (I am no genius, by far) and I have the spare time to do it. Now, this is just my two cents on the subject, but I feel as if it would just be a waste of time to do too much bike shedding on the abstract style ideas. There's a lot of 30,000 foot overviews of many concepts that leave you not really knowing what to do, where, and how. That's true of programming and of Wiki's, and it's easy to get bogged down in patterns and paradigms etc.

Another thing to consider, there are a lot of non-native English speakers with really good programming knowledge, yet not really enough control of English to manage Person/Mood/Voice. It's just my opinion, but if the text they write gets the idea across to the reader, it's good enough. I have the feeling that at the end of the day, we're more about code than "content" in the Wikipedia sense. Anything that is too jumbled to understand, a native English speaker can come in and try to make it flow better. But changing person/voice in a paragraph or text is actually a lot of detailed work that isn't coding. I can do it, but I hate doing it - and I think most other people would not actually do it either, so having a rule detailing what none of us are actually going to do is somewhat pointless.

Here are some ideas off the top of my head for practical guidelines for wiki content:

Any text without some kind of reference will be pretty dull. At the same time, managing footnotes and references is actually not fun, and can be a bit difficult to keep them up to date. Somehow I feel that keeping things informal, not trying to copy Wikipedia, and sticking to the Handmade ethic of not following the crowd but doing what works best for you, for a particular problem, at a particular time, is going to be the best way to play it.

With that said, my suggestion for linking is:

  • Prefer specific link locations - If you link to a video, try to include the play position in the link. To a webpage with anchors, remember the anchor if you can.
  • Linking to videos produced by the Handmade Community should use an abbreviation scheme, like Handmade Hero (Casey's vids) would be HMH followed by the episode number. So HMH22 is Handmade Hero Day 22.
  • Internal links to wiki articles should be the title of the article as the linked text.

References to books, manuals and so on:

  • Establish the title at an early stage in the article like so: "The C Programming Language, Kernighan & Ritchie, Prentice Hall 1st Ed. (K&R C)" and from that point on, all references to the text can be K&R C.
  • When referencing some part of a book, use an elipsis (K&R C, p. 84) and include the page number, if you can.
  • If you're linking to a blog post, use the full title of the blog post and link it, but create an acceptable abbreviation. If the post has sections/anchors, try to use those if you link again. Otherwise, just the abbreviation, unlinked, is fine.

While no one should ever plagiarize, I feel like a lot of benefit could be gotten by summarizing, or drawing attention to some point or code that is explained in a wider context within a book, or some archtectural issue, for instance something out of the intel programmers reference etc, in a Wiki article. There are already some good examples of this, like the GDB tutorial, and one on x86 assembly and so on.

At the same time, the internet is full of trivial introductions to topics that give you just enough information to mess everything up. I feel like there would be some benefit in focusing on topics, texts or talks that emphasize the Handmade Ethic of do it yourself, and deep knowledge. How that plays out though is really going to have to be up to individual authors.

Code

  • Aside from just formatting code, try to include non-trivial examples that are compilable. If you are working with some large portion of code (more than a visual page on a regular 1280 display), then consider putting the code in a git repository and linking to the full code in the article, with the choice examples for explanation.

  • Try not to refer to dependencies (either library or code) that are not shown. If you have some Global variable smack in the middle of an example that has no type information, no declaration or definition, then it's likely to be confusing.

  • Always include the actual working commandline to install. It helps to avoid the "how do I include $lib" or what not. If the build steps are more complicated than one line (they really shouldn't be) then consider including a full build.bat or build.sh.

  • I think most people come here (at least I did) through Handmade Hero, so I suggest code that sticks to that style of indentation and variable/function naming will make everything more consistent. I think this should be a very soft requirement. I seriously think style guides for programming are generally evil and the flame wars that ensue are a drain on everyones time. If anyone is wondering, my normal coding style is almost completely opposite from Casey's, I use snake_case where he uses PascalCase and vice versa. But then again, I don't mind changing.

It's just my opinion, but I think the bit of extra setup in code to get to the point you're going to discuss is usually worth the effort, so long as you are talking about something specific. If you move out to some stuff about designing a multi-platform interface, you should throw out the idea of providing fully working or compilable code. With that said, you should be clear that there's "more to it" than what you are showing, even though that would probably be obvious.

Also, in some cases you might show some code mockups to discuss commonly wrong ways of doing something, or bad code etc. In which case making a full compilable example is also pointless.

These are just some ideas, and I am not attached to any of them. Maybe someone with more experience or intelligence has better suggestions, and I am all for that.


Edited by Jason Martin on Feb. 20, 2018, 9:06 p.m.