Joined: 11 Apr 2001 Posts: 1554 Location: Silicon Valley
So here are some of my thoughts on this...
1) What are some logical categories that we can break the FAQ down into? I suppose we can also allow specific questions to belong to more than 1 category. In other words, the Solaris question that royr has already posted might belong both to a Solaris category, and an Installation / Configuation. This way, if we do decide to have categories for each platform, then if a question applies to Linux and Solaris but not NT, then links to it would appear in both of those categories. The structure is going to be maintained in a database, so we can think of creative ways of organizing this stuff...
2) How rich do we want to make the content. In other words, do we basically just have ASCII so that it can easily be ported to other formats, or do we use something along the lines of HTML so that we can embed not only typographic styles but even images or other media?
3) If basically what we are doing is repackaging threads from here and the listserv in an easy to read form, then the ability to find what one is looking for in the FAQ is of the utmost importance, because otherwise, I could just search the mqseries.net threads or look through the listserv archives. Therefore, we probably want to pay particular attention to keywords associated with each question, and use these to perform searches on rather than just do a full-text search. For instance, on this site, if you search for the word "channel" it will return every single post with that word regardless of revelance - there is no associated ranking of the results. We probably want to do this with the FAQ, provide some sort of google like search routine that will be a little smarter about what to return to the user. Of course, we would like to minimize the need to do searches altogether. If we come up with very good categories and subcategories, a user should be able to "drill-down" to a very specific set of questions to find exactly the one he/she is looking for in a small number of mouse-clicks...
_________________ Brandon Duncan
IBM Certified MQSeries Specialist
MQSeries.net forum moderator
About the rich content issue:
I think that the content should be separated from its appearance. Althogh several types of content would appear in the FAQ answers (text, URLs, images, binaries), I think they should be included separately and should not contain any formatting. The formatting can be added separately, thus enabling the rendering of the FAQ contents to various media types (ASCII, HTML, PDF, and so on) without rewriting it each time.
How about maintaining the FAQ as an XML document, and writing a separate XSL stylesheet to render it to each medium?
Something like this:
Code:
<FAQ>
<Question id='abcde'>Why do I get an 'internal error' message at crtmqm on Solaris?</Question>
<Keyword>Solaris</Keyword>
<Keyword>crtmqm</Keyword>
<Keyword>installation</Keyword>
<Keyword>internal error</Keyword>
<Answer id='1234' postedby='royr'>
This can be caused by ...
Brandon posted a list of kernel parameters <Link href=http://aaa.bbb>here</Link>.
Also see <Link answerid='3456'>this answer</Link>.
</Answer>
<Answer id='1235' postedby='someuser'>
Another answer is...
</Answer>
</FAQ>
An XSL stylesheet can easily be built to render this to ASCII or HTML with a TOC and an index by keywords or even by posters. Using an XSL-FO processor we can even create PDFs from it.
Note that the element may either contain an href attribute to another external document (or binary file), or a link to another answer or question in the FAQ.
Joined: 11 Apr 2001 Posts: 1554 Location: Silicon Valley
wow, I hadn't even thought of XML... I forgot about all the cool things you can do with it
That would definitely help make the FAQ an enduring document since it can be re-rendered to fit any medium we can dream up. Who knows, maybe someone trying to fix an MQSeries Everyplace bug on their WAP phone will pull up the MQSeries FAQ on it???
_________________ Brandon Duncan
IBM Certified MQSeries Specialist
MQSeries.net forum moderator
Joined: 20 Sep 2001 Posts: 1 Location: Blue Cross of Mo
What about a section for documentation like naming conventions, programming standards, administration standards. At some this all need to be created and it is useful to see what other are doing.
thanks larry
_________________ Larry McCord
Blue Cross and Blue Shield of Missouri
314.923.4432
mccordl@bcbsmo.com
wow, I hadn't even thought of XML... I forgot about all the cool things you can do with it
That would definitely help make the FAQ an enduring document since it can be re-rendered to fit any medium we can dream up. Who knows, maybe someone trying to fix an MQSeries Everyplace bug on their WAP phone will pull up the MQSeries FAQ on it???
You cannot post new topics in this forum You cannot reply to topics in this forum You cannot edit your posts in this forum You cannot delete your posts in this forum You cannot vote in polls in this forum