• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

All about the FAQ

 
Ranch Hand
Posts: 381
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
As the subject implies this post has some musings, suggestions etc. about the wiki/FAQ.

I have a few features that I kind of wish were there.

1) It would be swell to have a talk page or something so that you could see who is editing and why. There is a recent changes page but it is not very informative and at least for me every change appears to have been done by localhost so that doesn't really say anything.

I have been working specifically today on the JDBC FAQ. I have added a few things and I am expanding a few existing ones. But how would someone know why I have made any changes that I have? Or even (besides me saying here) that I have done so?

2) The FAQ overall has lots of good content but I think the organization needs to be standarized.

There seem to be two styles. On most of the pages each question or topic is listed as just another entry. On the JDBC FAQ page the questions and answers are all listed on that page but there are some other site references and links to expanded explanations where this is suitable.

Personally I prefer the second style but at any rate I am not sure what people here feel about styles or more to the point where this kind of thing should be discussed. I do think that a more consistent style will make a better overall FAQ.

I guess my goal would be to make the best Java FAQ on the net. It seems there has been plenty of quality contributions so far and I think my wishlist as it were is intended to take better (?) advantage this.
 
author
Posts: 14112
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Maximilian Stocker:
1) It would be swell to have a talk page or something so that you could see who is editing and why. There is a recent changes page but it is not very informative and at least for me every change appears to have been done by localhost so that doesn't really say anything.



Yes, there are some things that could work better. *Some* of those things could be fixed by installing a newer version of Friki, but the last time I tried, I failed for reasons I don't understand.


I have been working specifically today on the JDBC FAQ. I have added a few things and I am expanding a few existing ones. But how would someone know why I have made any changes that I have? Or even (besides me saying here) that I have done so?



Well, it *is* possible to look at the history of a page. The other features you describe could be nice, but I don't think they are really vital. In the end, it seems to be much less important to me to see who did what why, than to simply see the current state of a page.

There seem to be two styles. On most of the pages each question or topic is listed as just another entry. On the JDBC FAQ page the questions and answers are all listed on that page but there are some other site references and links to expanded explanations where this is suitable.

Personally I prefer the second style but at any rate I am not sure what people here feel about styles or more to the point where this kind of thing should be discussed. I do think that a more consistent style will make a better overall FAQ.



I'm not sure about this one. Personally, I don't like long pages, especially not in wikis. So, if the answer to a question is longer than just a simple sentence, I'll typically prefer it to be on its own page.


I guess my goal would be to make the best Java FAQ on the net.



Well, I certainly wouldn't object to it becoming the best Java FAQ on the net, but frankly that sounds like *a lot* of work. My personal goal currently is to simply make it help answer questions that are asked at JavaRanch, well, frequently.

Of course it's a wiki, so anyone who wants to invest his time to improve it is very welcome to do so!
 
Maximilian Xavier Stocker
Ranch Hand
Posts: 381
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Ilja,

Thank you for your feeback. My responses follow...

Yes, there are some things that could work better. *Some* of those things could be fixed by installing a newer version of Friki, but the last time I tried, I failed for reasons I don't understand.



I see. Well that's a good reason.

Well, it *is* possible to look at the history of a page. The other features you describe could be nice, but I don't think they are really vital. In the end, it seems to be much less important to me to see who did what why, than to simply see the current state of a page.



Well based on the first repsonse do you think we could maybe start a new talk page in case someone disagrees with an edit and undoes someone elses work. So that people can know why it happened? I guess this has never happened but I think at least in the JDBC one I could see it happen because the spec is not always clear and you may get different interpretations and ideas.

I'm not sure about this one. Personally, I don't like long pages, especially not in wikis. So, if the answer to a question is longer than just a simple sentence, I'll typically prefer it to be on its own page.



I would like to hear some other opinions on this. The JDBC one again seems different than most. And while I prefer it I think it would be better to be the same as the others. But I don't know what the history of the page is (in terms of why it is set up that way) so hopefully Jeanne or Bear or whoever did that one can provide some comment on this.

If there are no objections than I would like to change it so it is similar to the other FAQ's. For the record I think I would break it down in smaller subsections like General JDBC (for stuff on what JDBC is how drivers work etc), Connection FAQ for connection related issues and Usage FAQ for other stuff like my entry on PreparedStatement

Well, I certainly wouldn't object to it becoming the best Java FAQ on the net, but frankly that sounds like *a lot* of work.



You never know until you try. Of course as Homer J. would say "trying is the first step to failure" but I am optimistic. It's better than what I have seen already.
 
author and iconoclast
Posts: 24207
46
Mac OS X Eclipse IDE Chrome
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi Max,

Have you read much of The Original Wiki? This first Wiki (on the topic of design patterns and agile methodologies) often uses a sort of "conversation" style, where a paragraph is often followed by someone else's disagreeing paragraph, often in italics to set it off as a comment. People generally sign their comments. I like that approach, because it helps you to see all sides of a debate. Go have a look at that, and then c'mon back here and use that style in our FAQ, if you like.
 
author & internet detective
Posts: 41860
908
Eclipse IDE VI Editor Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Maximilian Stocker:
I would like to hear some other opinions on this. The JDBC one again seems different than most. And while I prefer it I think it would be better to be the same as the others. But I don't know what the history of the page is (in terms of why it is set up that way) so hopefully Jeanne or Bear or whoever did that one can provide some comment on this


The JDBC FAQ preceeded my moderating that forum, although I have added to it. I think it was just evolved that way though. The first few entries are pretty short. And after that, people (myself included) just used that style. You are certainly welcome to change it.
 
Ilja Preuss
author
Posts: 14112
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I think for a FAQ style wiki, I'd prefer to separate the answer to the question from the discussion of the answer. That is, have a page FooBar with the question and an answer, and (if appropriate) a link to a page FooBarDiscussion. (If I remember correctly, this would be similar to how wikipedia handles it.)

If a FAQ page becomes big, I'm all for splitting it, preferably by topic.
 
author and jackaroo
Posts: 12200
280
Mac IntelliJ IDE Firefox Browser Oracle C++ Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I think for some of the certification forums a long page might be better than a short page with multiple links to different answers, simply because someone just starting the certification would probably benefit from being able to read through all the questions and answers.

Otherwise I tend to agree with the idea of having a master page which lists the questions, each of which being a link to a page with the answer (and possibly opinions on the answer).

Regards, Andrew
 
Maximilian Xavier Stocker
Ranch Hand
Posts: 381
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Ernest Friedman-Hill:
Hi Max,

Have you read much of The Original Wiki? This first Wiki (on the topic of design patterns and agile methodologies) often uses a sort of "conversation" style, where a paragraph is often followed by someone else's disagreeing paragraph, often in italics to set it off as a comment. People generally sign their comments. I like that approach, because it helps you to see all sides of a debate. Go have a look at that, and then c'mon back here and use that style in our FAQ, if you like.



Hello Ernest,

I have seen other wiki's but I did look at that one as well. I think that is what I will do if I see a change or item I feel is incorrect.

I think the italics would help distinguish the comments from the content... at least I hope they would for normal users.

I really don't see much of an issue really yet I was more wondering what to do if it comes up.

Thank you for your valuable feedback.
 
Maximilian Xavier Stocker
Ranch Hand
Posts: 381
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Jeanne Boyarsky:

The JDBC FAQ preceeded my moderating that forum, although I have added to it. I think it was just evolved that way though. The first few entries are pretty short. And after that, people (myself included) just used that style. You are certainly welcome to change it.



Yes I think I am going to think about it some more but generally I think it should be split up into at least some subcategories to fall more in line with the other FAQs.

Thank you for the feedback Jeanne I figured you would know a bit about the style history... which you do.. even if it's just keep the same as before.

 
Maximilian Xavier Stocker
Ranch Hand
Posts: 381
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Thank you Ilja and Andrew,

I did read your post but it occurs to me if I keep responding to each individually it will take some time. But I did read them and thanks for the slightly differing viewpoints. I do have a clear idea of what I will do now in the JdbcFaq.

Thanks again to all who answered. I do appreciate the ideas, suggestions and viewpoints.
 
Maximilian Xavier Stocker
Ranch Hand
Posts: 381
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hello all,

As an update. I made a bunch of edits to reorganize that FAQ. I split up the current list into four question categories which in my experience (on other sites) I believe are the major problem areas and actually FAQs.

I also added a discussion page for the whole JDBC Faq after much thinking. I liked the comment idea but I decided in the end that it will probably be better not to add clutter to the actual FAQ's which I think would only confuse the target audience.

Anyway you can see it at http://faq.javaranch.com/view?JdbcFaq

Thanks again for all the input.
 
Andrew Monkhouse
author and jackaroo
Posts: 12200
280
Mac IntelliJ IDE Firefox Browser Oracle C++ Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi Maximilian,

That looks great. Well done.

Regards, Andrew
 
Jeanne Boyarsky
author & internet detective
Posts: 41860
908
Eclipse IDE VI Editor Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Nice. Thanks Maximilian!
 
Maximilian Xavier Stocker
Ranch Hand
Posts: 381
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Thanks Andrew and Jeanne.
 
reply
    Bookmark Topic Watch Topic
  • New Topic