 |
Here's where we need to describe what is good style for Javapedia articles.
First, keep it short, keep it simple. Here, "simple" does not mean "low level technically" -- we want deep technical content. It means "direct, clear, straightforward". Short sentences, direct statements, clear words.
Second is the same. Probably third, fourth, and fifth.
Write articles in a factual manner using a NeutralPointOfView.
When writing a Javapedia article there is no need to sign it. We want to encourage people to edit any articles they feel they can improve and if a section is signed that will discourage people from changing it.
Put any comments that discuss the changes needed in an article at the bottom of the page after double horizontal lines. Pleased sign your comments as that makes it easier to follow discussions and understand who said what.
When writing a sentence that contains a link to another article, it is suggested that you write the link as words separated by spaces so that it is easier to read. For example, when referring to the Javapedia Guidelines page use forced links (i.e. [[Javapedia Guidelines]]), instead of the WikiWord format (i.e. JavapediaGuidelines).
The following was moved from the JavapediaTodo page & the GoodStyle page since I'm not sure that the best style for the Javapedia is the same as for regular wiki pages. -- RonGoldman
- Is there any policy on adding signatures? It seems to me that they should not be allowed on pages.
I'm of the opinion attribution signatures should be used for significant contributions. I feel writing a full page plus article like SynchronizationIsSlowMisconception deserves some credit and it shows I'm willing to own up to my words and run the risk of being humiliated if I'm wrong. Trivial contributions like spelling corrections or making words into links or even a comment like this one, do not deserve formal attribution.
- This is a good question. I think I favor anonymous articles if only because that seems to encourage people to feel that they can make major changes to an article. If someone has signed material that they have written then I am much less willing to edit it. As the old comment on the GoodStyle page points out one can use the Diffs command to see who wrote what. Also the Wikipedia seems to favor anonymous articles, so if that works for them it should also work for us. I've added a point to the guidelines to suggest this.
For discussions like this I think it does help to sign one's comments. -- RonGoldman
What about Wiki links? Should they not be clear words with the wiki link hidden? In other words, GoodStyle should be replaced with Good Style.
- Another good question. Using forced links to insert spaces between words does seem to make a page more readable. However using a WikiWord might be better because it provides a model for wiki beginners to use to make links. Otherwise they are apt to write Good Style and wonder why it didn't create a link. For now I've added a suggestion that authors consider using forced links to make entries more readable, but that individual authors are free to use whatever style they prefer. -- RonGoldman
What about links to commonly used J2SE classes? Do we want to create topic pages for classes in java.lang? Or should we generally just assume the readers know where they are and not create a link? Granted, I can understand that if we create a topic page on this site, contributors can make comments about real world usage of the class. If we don't want an internal link should we put in an external link to the JavaDoc API on java.sun.com -- if so, which version of the JDK should we use? latest? -- Main.redwolf - 27 Aug 2003
How should the topics for Java primitives be named? I created one for "short" but the links from other topics won't work as it wants to display the "Short" topic. I could perhaps name it something like "ShortPrimitive" but then of course anyone who refers to it has to use a forced link. Anyone else who adds the other primitives should be aware of an
established convention. -- Main.redwolf - 27 Aug 2003
- Seems like a reasonable convention for now. -- RonGoldman
|