Wiki FAQ

dwks · 01-15-2008, 05:29 PM

Quote:

So how is the wiki coming along? All maintenance done and so, ready for contribution?

It's pretty good, and I'm already starting to link to it!

http://cboard.cprogramming.com/showp...5&postcount=10

Unfortunately you need index.php, as in cpwiki.sf.net/index.php/gets; cpwiki.sf/net/gets doesn't work. That's okay, though if there's a way to change this it would be fine by me. (Don't look at me, I didn't install it.

)

Quote:

As a side note, I've never used any other parser before and so when I checked out the examples dwks mentioned, I didn't understand much. They typically seem to assume you know about parser before learning how to use them.

Mmm, yes, they do usually.

You could try other tutorials. This one's okay: http://ds9a.nl/lex-yacc/cvs/output/lexyacc.html (or all on one page, useful for saving: http://ds9a.nl/lex-yacc/cvs/lex-yacc-howto.html)

Or you could get a book on the topic. Books usually explain things better.

Or you could give up and stick with writing your own.

Elysia · 01-19-2008, 03:26 PM

So I made a draft about indentation:
http://cpwiki.sourceforge.net/index.php/Indentation
Undoubtedly, there are things you might not agree with, especially the tabs/spaces section, so any suggestions or fixes are welcome.

GanglyLamb · 01-19-2008, 04:00 PM

About the tabs, you might want to add that you can always have some setting so that a tab is automatically converted to lets say 2 spaces... You gain the pros from tab usage (one keystroke for 2 or more spaces) and the cleannes from spaces as in they all look the same everywhere.

:edit:
nvm if this was already there but i just took a quick peak at it

.

Elysia · 01-19-2008, 04:23 PM

Yeah, it's listed under spaces, because basically it IS spaces and are treated as such, so it's a little pro/con in itself, as I've listed it I think.

whiteflags · 01-19-2008, 06:01 PM

Hm, it's a good draft. I already have a list of things I'd like to see done to it.

It could benefit from some sectioning. I think we should make clear distinctions between the problem, proper style choices, and maybe a section on tabs vs. spaces, so that we can lay out a table of contents.

I'm sure that dwks didn't intend this to be the case but sections of the article sound a bit patronizing and et cetera. To pull a quote, "But how do we fix it? It's not difficult--you do not need to be afraid at all." Unnecessarily rude! Like other archives of information, we should strive to be objective and avoid use of loaded words.

No unnecessarily capitalized phrases: we should be using bold or italics for emphasis in lieu of "screaming."

I'll get started on what I think needs to be done to the article when I find free time (I'd need to learn a lot before I know how it works). If there are any skilled individuals who understand how wikimedia works already, maybe they can get started?

Elysia · 01-19-2008, 06:34 PM

I don't know how exactly to phrase it, not that it's very rude. But anyway, so I rephrased it a little. I don't know if it's better, since I don't know 100% what you're striving to achieve.

whiteflags · 01-19-2008, 08:16 PM

You've never read an encyclopedia before? Most of any one volume is written in third person point-of-view. You have no reason to mention yourself or talk to anyone about their abilities; how easy something is or how new they are to a topic.

I just find it to be very inappropriate to point out that it's their fault they are reading the article, and as a gesture to the reading public you keep yourself and them out of it and give them that respect. The existing FAQ is not so assuming: It's not that they did something wrong and you can fix it for them, you're giving them advice.

To be explicit, I wrote a shorter spiel on indentation which I am considering publishing in place of yours:

Quote:

Indentation

Indentation refers to the spacing that occurs before a line begins in a source file, and is one part of an umbrella term, programming style: the personal or sometimes professional preferences of programmers (such as the habits of hobbyist programmers, or style guidelines used in the workplace) which make programming instructions more presentable or legible.

Our web site has no formal style guidelines; however, from a presentability and legibility standpoint, it is easier to maintain and read code that is carefully indented. At our site, we strongly encourage people to adopt some indentation standards for themselves so that they find using the message boards a more helpful and fleeting experience and are more prepared to work on projects with others.

Indentation as a Model of Consistency

As in writing, one style does not suit all the programmers in the world. Apart from expectations in the workspace, programmers will commonly differ on several points concerning indentation and programming style, mostly out of personal preference.

Most view indentation as a presentation model that simply needs consistency and consideration for the medium where the code will be printed or displayed. For instance, at cboard, we often see code indented with a mixture of tabs and spaces instead of picking one or the other and unintentionally causing it to be formatted improperly by browsers in a fixed-width font. For this reason, it should be considered an unspoken rule that on forums and other virtual mediums, spaces rule, whereas tabs may rule in the realm of IDEs or the printed medium.

Achieving consistency is easy if you choose to adopt an already existing style such as K&R or Allman style, however, programmers sometimes develop their own tastes and opinions about what “looks good” through programming experience. Common considerations in the format of any style guideline are:

placement of braces and parenthesis
spacing between operators
tab length (or the sum of the spaces from the beginning of a line)
the arrangement and format of comment lines

Individuals may find it rewarding to rotate their indentation styles to keep their work from getting repetitive or simply getting used to a style they may be expected to use more commonly. It is equally imprortant to avoid deviating from the style, and to never rotate styles in the middle of a source file or project, where the indentation may become a distraction.

I would add links to documents to teach and explain the specific styles I mentioned at least, and perhaps try to find some helpful threads to link to as well. I would also keep at least one code example like in your article.

But I'd like to get some feedback on the quoted before I rewrite.

**laserlight** · 01-20-2008, 12:45 AM

Oh wait, who decided on using the GNU FDL 1.2 for the cpwiki license? Wikipedia itself may be under the GNU FDL, but that does not necessarily mean that it is the best license for an FAQ/wiki/documentation. See:
Why You Shouldn't Use the GNU FDL
Why the Wikimedia projects should not use GFDL as a stand alone license for images
General Resolution: Why the GNU Free Documentation License is not suitable for Debian main

It might not really matter in the end considering many people quote from Wikipedia as if the content was in the public domain, but the legally pedantic side of me says we should go for a more appropriate license (e.g., some Creative Commons license, the Academic Free License, or the Open Software License). Yet before we can do that, we need to decide on the restrictions/freedoms that we want for the content, and even who actually owns the copyright to the cpwiki content (keeping it the property of contributors versus the property of one legal entity).

Quote:

I don't know if it's better, since I don't know 100% what you're striving to achieve.

I would rather see an FAQ answer with facts, not opinion. For example, you wrote about some "rules", but the one on brace placement is more like personal opinion of which style is best.

Quote:

For this reason, it should be considered an unspoken rule that on forums and other virtual mediums, spaces rule, whereas tabs may rule in the realm of IDEs or the printed medium.

Is this really true? I would rather be neutral and recommend both the all spaces and all tabs approach for indentation. We could also provide the pros and cons of both in another section, so a more conscientious reader can decide for himself/herself instead of randomly picking one.

Quote:

I would add links to documents to teach and explain the specific styles I mentioned at least

esr's The Jargon File entry on indent style could be a possible link.

whiteflags · 01-20-2008, 01:57 AM

Quote:

Is this really true? I would rather be neutral and recommend both the all spaces and all tabs approach for indentation. We could also provide the pros and cons of both in another section, so a more conscientious reader can decide for himself/herself instead of randomly picking one.

Well this is the kind of reason why I asked for opinions. Even I make mistakes, but you're absolutely right. Perhaps the best solution is to just replace that sentence with one referring to the tabs vs. spaces section.

Great. I'll make the rewrite happen and report back.

Okay. More like it?

Elysia · 01-20-2008, 05:54 AM

Quote:

Originally Posted by citizen

You've never read an encyclopedia before? Most of any one volume is written in third person point-of-view. You have no reason to mention yourself or talk to anyone about their abilities; how easy something is or how new they are to a topic.

I have read many such articles before and have strived to written some as well.

Quote:

I just find it to be very inappropriate to point out that it's their fault they are reading the article, and as a gesture to the reading public you keep yourself and them out of it and give them that respect. The existing FAQ is not so assuming: It's not that they did something wrong and you can fix it for them, you're giving them advice.

So in essence, you view it as something directed at people who do not understand the topic and not as general advice?

Quote:

To be explicit, I wrote a shorter spiel on indentation which I am considering publishing in place of yours:

Except yours isn't very informative and uses typical complex language. I like to follow the KISS principle. Keep it simple and don't make it complex.

Quote:

I would rather see an FAQ answer with facts, not opinion. For example, you wrote about some "rules", but the one on brace placement is more like personal opinion of which style is best.

So it is. There's no rule to that, is there?
However, when touching coding styles, I also believe that you should pick to suit yourself and make your code as readable as possible.
And putting braces on their own line makes it more readable, at least to me.
If you would suggest another approach, I'm open to suggestions.

EDIT:
So you changed the entire ARTICLE? I don't believe I agree.
I don't think it's a good idea to replace everything someone else just wrote without at least discussing it first.

**laserlight** · 01-20-2008, 05:58 AM

I suggest that the Cite/Cite.php extension for MediaWiki be installed. It would make citing references easier and more consistent. As an occasional Wikipedia contributor, it took me awhile to figure out why my normal citation method was not working, and how to fix it, but I think that this extension is the fix.

Quote:

Okay. More like it?

I am fine with it for the most part. Perhaps the discussion page for articles should be used instead of relying of this forum for such specific discussions?

Quote:

However, when touching coding styles, I also believe that you should pick to suit yourself and make your code as readable as possible.
And putting braces on their own line makes it more readable, at least to me.

As such, you should state what are the good options, and leave it to the reader to choose. After all, if the reader is already using a consistent and acceptable style, it does not make sense for him/her to change to conform to your style.

Quote:

I don't think it's a good idea to replace everything someone else just wrote without at least discussing it first.

I agree, citizen should have waited for your input. Thankfully, these wiki software typically include a primitive version control system, so we can always revert back if need be.

Elysia · 01-20-2008, 06:05 AM

I put my version back at http://cpwiki.sourceforge.net/index....ntation_Elysia for now.
I'm going to see how to better improve the article.

**laserlight** · 01-20-2008, 06:09 AM

Quote:

Originally Posted by Elysia

I put my version back at http://cpwiki.sourceforge.net/index....ntation_Elysia for now.
I'm going to see how to better improve the article.

It might make more sense to put it under User:Elysia/Indentation instead of creating a new article at the root of the wiki.

Elysia · 01-20-2008, 06:12 AM

Good idea. I don't know if it's possible to remove pages from the wiki, though. Perhaps someone with more administrative powers can do so.

whiteflags · 01-20-2008, 02:56 PM

>> So in essence, you view it as something directed at people who do not understand the topic and not as general advice?

No. But you didn't write an article that gives general advice, just advice that you're sure was best. Apparently you don't know how to write from a third person perspective, and that is a problem to me.

>> Except yours isn't very informative and uses typical complex language. I like to follow the KISS principle. Keep it simple and don't make it complex.

I never made the claim that the article was complete, or even the best alternative, but I do believe it to be a significant improvement. Instead of whining, perhaps you can propose something? I wouldn't mind if you edited my "typical complex language" with KISS stuff. I only expect you to write it from a third person perspective and keep your opinions out of it. That's my approach and I hope that you are open to this suggestion.

>> I don't think it's a good idea to replace everything someone else just wrote without at least discussing it first.

You wrote the original article without discussing it first. Crappy double-standard is crappy.

Well I'm glad that you also took matters into your own hands and published TWO articles. This whole idea is not going to get anywhere unless we work together. But I've done what I thought I needed to do. I'll write myself out of the conversation if I need to as well.

01-19-2008, 04:00 PM	#93
GanglyLamb and the Hat of Clumsiness Join Date: Oct 2002 Posts: 1,101	About the tabs, you might want to add that you can always have some setting so that a tab is automatically converted to lets say 2 spaces... You gain the pros from tab usage (one keystroke for 2 or more spaces) and the cleannes from spaces as in they all look the same everywhere. :edit: nvm if this was already there but i just took a quick peak at it .
GanglyLamb is offline

01-19-2008, 06:01 PM	#95
whiteflags MENTAL DETECTOR Join Date: Apr 2006 Location: United States Posts: 3,292	Hm, it's a good draft. I already have a list of things I'd like to see done to it. It could benefit from some sectioning. I think we should make clear distinctions between the problem, proper style choices, and maybe a section on tabs vs. spaces, so that we can lay out a table of contents. I'm sure that dwks didn't intend this to be the case but sections of the article sound a bit patronizing and et cetera. To pull a quote, "But how do we fix it? It's not difficult--you do not need to be afraid at all." Unnecessarily rude! Like other archives of information, we should strive to be objective and avoid use of loaded words. No unnecessarily capitalized phrases: we should be using bold or italics for emphasis in lieu of "screaming." I'll get started on what I think needs to be done to the article when I find free time (I'd need to learn a lot before I know how it works). If there are any skilled individuals who understand how wikimedia works already, maybe they can get started?
whiteflags is offline

01-20-2008, 02:56 PM	#105
whiteflags MENTAL DETECTOR Join Date: Apr 2006 Location: United States Posts: 3,292	>> So in essence, you view it as something directed at people who do not understand the topic and not as general advice? No. But you didn't write an article that gives general advice, just advice that you're sure was best. Apparently you don't know how to write from a third person perspective, and that is a problem to me. >> Except yours isn't very informative and uses typical complex language. I like to follow the KISS principle. Keep it simple and don't make it complex. I never made the claim that the article was complete, or even the best alternative, but I do believe it to be a significant improvement. Instead of whining, perhaps you can propose something? I wouldn't mind if you edited my "typical complex language" with KISS stuff. I only expect you to write it from a third person perspective and keep your opinions out of it. That's my approach and I hope that you are open to this suggestion. >> I don't think it's a good idea to replace everything someone else just wrote without at least discussing it first. You wrote the original article without discussing it first. Crappy double-standard is crappy. Well I'm glad that you also took matters into your own hands and published TWO articles. This whole idea is not going to get anywhere unless we work together. But I've done what I thought I needed to do. I'll write myself out of the conversation if I need to as well. Last edited by whiteflags; 01-20-2008 at 03:00 PM.
whiteflags is offline

Thread Tools
Show Printable Version Email this Page
Display Modes
Linear Mode Switch to Hybrid Mode Switch to Threaded Mode

Similar Threads
Thread	Thread Starter	Forum	Replies	Last Post
Wiki FAQ	Queatrix	General Discussions	6	03-25-2007 03:39 AM
Wiki for Tutorials	jverkoey	General Discussions	7	08-16-2005 03:03 PM
FAQ Check/Lock	RoD	A Brief History of Cprogramming.com	2	10-15-2002 11:21 AM