DocForge:Water cooler/Archive 2007

From DocForge

The water cooler is DocForge's metaspace: it's where we meet to talk about what we're doing, why we're doing it, and what's coming up next.

[edit] Article/category titles: capitalization, singular

Hi everybody,

Right now, the DocForge standard seems to be to capitalize all words in the title (e.g. Regular Expressions, Bash Shell Scripting, Superglobals (PHP)).

May I suggest we use the Wikipedia naming conventions? Some of the reasons they would be better are:

• Wikis are designed with quickly linking pages to each other in mind. When we're writing articles, it's hard to remember whether we need to link to Regular Expressions or regular expressions. If one, unambiguous rule was in effect, we could go with that every time.
• MediaWiki is designed with initial-capitalized, singular titles in mind. For instance, I can refer to a particular regular expression, then refer to multiple [[regular expression]]s (which appears as regular expressions), and the software will link to the article correctly. On the other hand, using the plural as the article title requires me to either set up a redirect page at regular expression, or write a oddly phrased sentence ("you can use a simple regular expression" -> "you refer to the page on Regular Expressions"). And chasing down multiple redirects can be a real pain =).
• The Wikipedia idea has always been 'one page for a subject', not one page for an article. It makes more sense (atleast, in my head) to have a page about regular expressions, which refers to a page about Perl or a page about Microsoft Windows, as opposed to having pages on Regular expressions in Perl or Installing Perl on Microsoft Windows. Although, on the other hand, that's what Ward's Wiki uses, and while their website is pretty messy, it's also always a fun read. So maybe that's where you want to go with DocForge?

Thanks for your attention; if there's a good reason for sticking with capital letters, I can be convinced, but in my semi-humble opinion, singular/initial-capital would be the way to go.

cheers, Gaurav 23:34, 18 February 2007 (EST)

I've been thinking about this problem. I prefer to see page titles with every word capitalized (since they're titles). But quickly linking is more important. Plus many people are already familiar with Wikipedia's standards, so in this case it's best to generally use their convention. You raise very good points. It's important to note, though, that this is a general guideline, not an absolute rule. See the new page at DocForge:Naming conventions.

One page per subject won't always work well here. In general it's good practice, but it won't be the rule. My editing style has been to let pages grow organically and split when they get large. For example, Regular Expressions is getting long. I'm about to add a reference to PHP's regex functions, but I'll put them in a new page. As long as we're rigorous with editing, cross-referencing, and categorizing, we won't standardize on "one page per subject" yet. But we'll watch to make sure things don't get out of hand.

Thanks for your input. This page is a very good idea. - Matt 10:02, 19 February 2007 (EST)

[edit] Duplication and a wiki for code

(Moved from Talk:Main Page)

Hard to know where to start. There are so many places that have such great descriptions of things, I'm not sure how much this helps.

For instance: WikiBooks has huge articles on programming details, data structures, Java and many other languages already in existance. I contribute there at times.

As a programmer, my main goal in life is to eliminate duplication.

On the other hand, if anyone is interested I have a project I'd really like to do that I think hasn't been done.

I'd like a WIKI where each page is actual, runnable code--a full class that solves a problem. The whole WIKI would be a giant library.

In a perfect world, classes could even be combined and downloaded, possibly even compiled on the server, pulling in required "includes" from other areas of the WIKI and delivering a finished product. (references would obviously have to be to a specific version of a wiki page... can't have someone inserting bad code after the fact).

Obviously it would have to be language dependent (or have language dependent sections).

It might even be that the article would describe the code and what is currently the "Talk" page would contain the code. For Java, the main page could be generated from the Javadocs of the talk/code page.

If anyone is interested in doing something like this, please reply here. I'll bookmark this page and watch for replies for a few weeks at least.

Bill.

To me your project idea sounds exactly like Subversion (svn) with the addition of a web interface which lets you create new versions of any file. Svn even supports includes from other repositories (i.e. dependancies). I hear your concerns over duplication, but wikibooks are very incomplete (look at PHP), do not allow every kind of article, and I don't like how it's organized for programming topics. So our goal here is to produce a better source of information by having the whole site dedicated to the one topic. - Matt 14:53, 16 February 2007 (EST)

The important things I'd really love to see in a server like this are--zero setup, install or configuring, public repository, browser based, indexed.

I thought SVN was just a version control system. If there is a way I can web in and start coding in a public repository, please post a pointer.

As for wikibooks, why not fix them, or at least reference them where they are good enough? -bill.

Why would you ever, in any possible scenario, want to allow strangers to execute or compile arbitrary code on your server? The security implications of what you're suggesting are staggering.

Furthermore, a project like this would clearly ingratiate itself to copy-and-paste developers, who would grab large pieces of code wholesale without any understanding of how the item works, and then expect (or possibly demand) that the author support the code they wrote! And what about code snippets that are novel and worth documenting, but are not deserving or useful as part of a standardized module?

The idea of "eliminating duplication" is a noble one, but is inherently misguided. If Wikipedia has taught us anything, it's that having a single authoritative source is difficult at best, and possibly a bad idea altogether. Any kind of research, in any topic, demands access to multiple sources by multiple authors. --Phil 15:10, 16 February 2007 (EST)

I don't believe I ever mentioned executing code on a server. Is this something you consider necessary? I don't think it would be safe either.

Also, there are lots of copy-and-paste sites out there, I'd prefer something that could be used more like the JDK is used, classes that are well documented and checked/refined by many people for usability--code that can be used directly or extended without modification (the best case instead of, as you suggested, the worst).

The ability to compile on the server would also assure that most of the code was actually runnable--the code that was not runnable would be immediately noticeable.

Anyway, if nobody's interested I may just do it myself--shouldn't be too hard with the mediawiki codebase--hardest part is going to be syntax checking in the editor. --bill

[edit] OpenID

OpenID should really be added as a way to login here, I think. There are multiple reasons for this: OpenID is a good thing, IMHO + it'll encourage editing/creation of new articles (especially now that the community is so small, this could help. Every addition really enhances DocForge at this stage.) - Ludo

I agree. I took a look at the OpenID MediaWiki extension when I was setting up DocForge. It's not as well integrated as I'd like it to be. It's also in beta and hasn't been tested with 1.9.x. I'd very much prefer the feature to be part of the MediaWiki core. But what I might look into is completely replacing DocForge's regular login with the extension. I'll give it a test very soon and note here how it goes. Thanks for the suggestion. --Matt 10:35, 15 March 2007 (EDT)