UnGood

[learnedax]

You know, default WikiStyle really annoys me. Using it for most purposes results in forced intercapping, e.g. ManageMent, which is usually both ugly and confusing. But at least that can be avoided with [[bracketing stuff]], so you are not required (just highly encouraged) to use the WikiStandard of GoodStyle (which is a pretty 1984 way of putting it, anyway). The worse problem is that when it's used for things that are already intercapped, like ClassName, it automatically creates dead links for you. You often don't want to create a new WikiPage any time you mention an object or method, so you have to then specially mark it up to prevent parsing as a WikiLink.

I have now run into several cases of annoying kludges in both directions, which makes me wonder who thought this system made any GoodSense in the first place?

Comments

[learnedax.livejournal.com]

you (not you, but somebody) *do* want to have a WikiLink for each object or method

Frequently that is true. The specific case that just made me think of this was one where code was not being documented, but rather referenced in minutes of a meeting. The notetaker wrote something like "this should be handled in FooClass" and thus got left with a dead link.

There are also cases where your documentation refers to, say, JLabel, which you are not responsible for documenting. The best thing might be to make a new page for each such reference that redirects to Sun's pages, but that's a huge amount of added work.

(Actually, the best thing there is to use Javadoc and not Wiki, but it's just an example.)