GeeCON Prague 2014*
The moose likes Ranch Office and the fly likes All about the FAQ Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


JavaRanch » Java Forums » This Site » Ranch Office
Bookmark "All about the FAQ " Watch "All about the FAQ " New topic
Author

All about the FAQ

Maximilian Xavier Stocker
Ranch Hand

Joined: Sep 20, 2005
Posts: 381
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.
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
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!


The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Maximilian Xavier Stocker
Ranch Hand

Joined: Sep 20, 2005
Posts: 381
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.
Ernest Friedman-Hill
author and iconoclast
Marshal

Joined: Jul 08, 2003
Posts: 24187
    
  34

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.


[Jess in Action][AskingGoodQuestions]
Jeanne Boyarsky
author & internet detective
Marshal

Joined: May 26, 2003
Posts: 30586
    
154

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.


[Blog] [JavaRanch FAQ] [How To Ask Questions The Smart Way] [Book Promos]
Blogging on Certs: SCEA Part 1, Part 2 & 3, Core Spring 3, OCAJP, OCPJP beta, TOGAF part 1 and part 2
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
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.
Andrew Monkhouse
author and jackaroo
Marshal Commander

Joined: Mar 28, 2003
Posts: 11465
    
  94

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


The Sun Certified Java Developer Exam with J2SE 5: paper version from Amazon, PDF from Apress, Online reference: Books 24x7 Personal blog
Maximilian Xavier Stocker
Ranch Hand

Joined: Sep 20, 2005
Posts: 381
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

Joined: Sep 20, 2005
Posts: 381
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

Joined: Sep 20, 2005
Posts: 381
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

Joined: Sep 20, 2005
Posts: 381
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
Marshal Commander

Joined: Mar 28, 2003
Posts: 11465
    
  94

Hi Maximilian,

That looks great. Well done.

Regards, Andrew
Jeanne Boyarsky
author & internet detective
Marshal

Joined: May 26, 2003
Posts: 30586
    
154

Nice. Thanks Maximilian!
Maximilian Xavier Stocker
Ranch Hand

Joined: Sep 20, 2005
Posts: 381
Thanks Andrew and Jeanne.
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: All about the FAQ