Re: knowledge base - was Re: RFC: mod_perl 2.0 documentation project
On Thu, 9 Aug 2001, Jim Smith wrote: > On Thu, Aug 09, 2001 at 07:31:11PM +0800, Stas Bekman wrote: > > This all sounds cool. I have a few concerns with this proposal: > > > > - source documents living under modperl cvs are to be written in POD. > > The project that you suggest should be able to accept this and other > > formats as a source. Afterwards it can convert it to many other formats. > > Matt has already done some work on porting PODs into XML. > > I don't see this as a problem. I was just picking a format out of the air > as a starting point. TMTOWTDI and PCDAA (Perl Can Do Almost Anything). that's cool. > > - where the actual converted knowledge base will be hosted? I mean who > > will host the production version? It's possible that we can get a > > machine at apache.org, but this is one of the things to worry about. If > > things need to be dynamically generated, we cannot do this from the same > > machine the modperl-site is hosted on (daedalus). > > I can't answer that at the moment. We can start worrying about that later, once we get something to show. I hope ASF can support that and may be use this project for other ASF projects if something really cool and/or useful will be produced. > > - we need someone to commit to lead the project, or things would never > > take off just like it has happened before. > > Well, I can lead the code development, but I can't commit to anything more > than that at the moment. I won't be able to do even that until after the > semester starts (classes start 27 Aug, we have several things to get done > before then). Oh, that's absolutely fine. We aren't in hurry at all. We have not many docs written yet anyway. This is something that we should do in parallel with the actual docs writing. > > > Now to see if I can get my boss to support me spending time on such a > > > project :) > > > > I hope he does. Really! > > He was very receptive yesterday evening. Wants to see a proposal > (what TAMU would be committing to) before giving the final go ahead. > We will probably need to involve our helpdesk people in some of the > user-interface design. We will need a design document before coding > so we know what we're aiming at. I can lead on that. Fantastic. We can discuss things here. If the discussion becomes to heavy and getting unrelated to mod_perl list, we can move it elsewhere. e.g. [EMAIL PROTECTED] or if you host the project on sourceforge, we can use their list. _ Stas Bekman JAm_pH -- Just Another mod_perl Hacker http://stason.org/ mod_perl Guide http://perl.apache.org/guide mailto:[EMAIL PROTECTED] http://apachetoday.com http://eXtropia.com/ http://singlesheaven.com http://perl.apache.org http://perlmonth.com/
Re: knowledge base - was Re: RFC: mod_perl 2.0 documentation project
On Thu, Aug 09, 2001 at 07:31:11PM +0800, Stas Bekman wrote: > This all sounds cool. I have a few concerns with this proposal: > > - source documents living under modperl cvs are to be written in POD. > The project that you suggest should be able to accept this and other > formats as a source. Afterwards it can convert it to many other formats. > Matt has already done some work on porting PODs into XML. I don't see this as a problem. I was just picking a format out of the air as a starting point. TMTOWTDI and PCDAA (Perl Can Do Almost Anything). > - where the actual converted knowledge base will be hosted? I mean who > will host the production version? It's possible that we can get a > machine at apache.org, but this is one of the things to worry about. If > things need to be dynamically generated, we cannot do this from the same > machine the modperl-site is hosted on (daedalus). I can't answer that at the moment. > - we need someone to commit to lead the project, or things would never > take off just like it has happened before. Well, I can lead the code development, but I can't commit to anything more than that at the moment. I won't be able to do even that until after the semester starts (classes start 27 Aug, we have several things to get done before then). > > Now to see if I can get my boss to support me spending time on such a > > project :) > > I hope he does. Really! He was very receptive yesterday evening. Wants to see a proposal (what TAMU would be committing to) before giving the final go ahead. We will probably need to involve our helpdesk people in some of the user-interface design. We will need a design document before coding so we know what we're aiming at. I can lead on that. --James
Re: knowledge base - was Re: RFC: mod_perl 2.0 documentation project
On Wed, 8 Aug 2001, Jim Smith wrote: > On Wed, Aug 08, 2001 at 10:45:43AM +0800, Stas Bekman wrote: > > On Tue, 7 Aug 2001, Jim Smith wrote: > > > > > On Tue, Aug 07, 2001 at 10:16:26PM +0800, Stas Bekman wrote: > > > > > Just some pseudo-random ideation boiling down to "let's use mod_perl > > > > > to buils a knowledge base" both to demonstrate it's power and to serve > > > > > the community. > > > > > > > > I like the idea!!! > > > > > > If we can come up with a proposal for a generic knowledge base product that > > > would be useful in an IT environment, I can probably devote some of my work > > > to it -- this is something I've been wanting to put together at work for > > > customers and our help desk people but haven't had time yet to get it all > > > together. I'll have more time in September after the students return. > > > > go ahead and be the first to propose Jim :) > > Ok... here are some of my initial thoughts. > > We need to be able to enter arbitrary documents, so I suggest DocBook > as the standard format. This handles articles, books, reference > pages, etc., in a well-defined manner. It also allows us to transform > to other formats without much of a problem. We can even consider > AxKit for at least part of the web interface. > > We would want to have different sections for documents that are not > related. For example, we (here at TAMU) could use a section on Unix, > another on Mac, and yet another on Windows systems. Or we could > divide it up by services. The different sections would not expect > overlap in keyword -> content mapping, so we could have an > AI::Catagorize object for each section that could provide a default > set of keywords. As we entered documents, those objects could learn > which keywords were appropriate. > > We would want to have documents in multiple catagories. This might > require the person entering the document enter multiple sets of > keywords, one per section. > > We would need to index on keyword so people could quickly find the > documents. Perhaps even a catelogue-style interface for browsing that > would be based on keyword categories. This would require some work. > (Broad categories are indicated by the presence of certain keywords, > or by a weighted average so a document having all but a couple of the > appropriate keywords won't be dropped from that category.) > > Documents shouldn't have to be entered via the web interface, though > they could be. We could provide a set of web-page templates for each > of the DocBook formats (well, the small ones anyway - don't want to > write a book via a web interface). Might want to even integrate with > WebDAV and a repository. > > We probably want to set up a SourceForge project if this is a go. > Any ideas on names? This all sounds cool. I have a few concerns with this proposal: - source documents living under modperl cvs are to be written in POD. The project that you suggest should be able to accept this and other formats as a source. Afterwards it can convert it to many other formats. Matt has already done some work on porting PODs into XML. - where the actual converted knowledge base will be hosted? I mean who will host the production version? It's possible that we can get a machine at apache.org, but this is one of the things to worry about. If things need to be dynamically generated, we cannot do this from the same machine the modperl-site is hosted on (daedalus). - we need someone to commit to lead the project, or things would never take off just like it has happened before. > Now to see if I can get my boss to support me spending time on such a > project :) I hope he does. Really! _ Stas Bekman JAm_pH -- Just Another mod_perl Hacker http://stason.org/ mod_perl Guide http://perl.apache.org/guide mailto:[EMAIL PROTECTED] http://apachetoday.com http://eXtropia.com/ http://singlesheaven.com http://perl.apache.org http://perlmonth.com/
Re: knowledge base - was Re: RFC: mod_perl 2.0 documentation project
On Wed, Aug 08, 2001 at 10:45:43AM +0800, Stas Bekman wrote: > On Tue, 7 Aug 2001, Jim Smith wrote: > > > On Tue, Aug 07, 2001 at 10:16:26PM +0800, Stas Bekman wrote: > > > > Just some pseudo-random ideation boiling down to "let's use mod_perl > > > > to buils a knowledge base" both to demonstrate it's power and to serve > > > > the community. > > > > > > I like the idea!!! > > > > If we can come up with a proposal for a generic knowledge base product that > > would be useful in an IT environment, I can probably devote some of my work > > to it -- this is something I've been wanting to put together at work for > > customers and our help desk people but haven't had time yet to get it all > > together. I'll have more time in September after the students return. > > go ahead and be the first to propose Jim :) Ok... here are some of my initial thoughts. We need to be able to enter arbitrary documents, so I suggest DocBook as the standard format. This handles articles, books, reference pages, etc., in a well-defined manner. It also allows us to transform to other formats without much of a problem. We can even consider AxKit for at least part of the web interface. We would want to have different sections for documents that are not related. For example, we (here at TAMU) could use a section on Unix, another on Mac, and yet another on Windows systems. Or we could divide it up by services. The different sections would not expect overlap in keyword -> content mapping, so we could have an AI::Catagorize object for each section that could provide a default set of keywords. As we entered documents, those objects could learn which keywords were appropriate. We would want to have documents in multiple catagories. This might require the person entering the document enter multiple sets of keywords, one per section. We would need to index on keyword so people could quickly find the documents. Perhaps even a catelogue-style interface for browsing that would be based on keyword categories. This would require some work. (Broad categories are indicated by the presence of certain keywords, or by a weighted average so a document having all but a couple of the appropriate keywords won't be dropped from that category.) Documents shouldn't have to be entered via the web interface, though they could be. We could provide a set of web-page templates for each of the DocBook formats (well, the small ones anyway - don't want to write a book via a web interface). Might want to even integrate with WebDAV and a repository. We probably want to set up a SourceForge project if this is a go. Any ideas on names? Now to see if I can get my boss to support me spending time on such a project :) --jim
Re: RFC: mod_perl 2.0 documentation project
On Tue, 7 Aug 2001, Barrie Slaymaker wrote: > On Tue, Aug 07, 2001 at 10:16:26PM +0800, Stas Bekman wrote: > > [Barrie, I hope you don't mind that I put it on the list, the more people > > contribute the better the outcome :)] > > Not at all, I just noticed that others seem to have replied directly and > followed suit. yup, whoever wants to dive in, please keep the posts on the list. Don't be shy. > > Something like this: http://perl.apache.org/guide/troubleshooting.html ? > > That's what made me think of it. That deals with a lot of the common > ones, I was thinking of something more open-ended that would grow to > contain more symptoms and (where useful) more details on how to fix > things. For instance, including the failures found in a lot of > systems would mean covering various tempalting system failures. When creating this page, I've followed a simple rule: when somebody asks a new question and gets an answer, I ignore it, unless the answer is really interesting and covers more than the question's scope. When the same question gets repeated, I add the Q&A to the troubleshooting chapter. Thus I've avoided having this page bloated. I believe it's probably not a good idea to collect all Q&As, because the content will become very hard to maintain and harder to navigate. > One of the great things about Perl and mod_perl is the diversity, but > it's also daunting to newcomers to identify all the peices and what > might be wrong, especially in a troubleshooting situation. Not if they use the search interface, you type in your symptom and you come up with hits. Let's say you see the error: "Apache.pm failed to load!", I go to the search input, type in the symptom and the first hit that comes is http://thingy.kcilink.com/modperlguide/troubleshooting/_Apache_pm_failed_to_load_.html May be the problem is in educating users how to use, and not how to store the data. I've never claimed the the current guide is easy to navigate, unless you read it all. But I think the search engine on the split version of the guide does a great job. I use it quite a lot by myself. > > The problem with DB, is maintence. When it's flat, people read mostly > > sequentially, point out and fix problems. When it's in the DB, most of the > > items would hardly come up and it's easier to have stale data in there. > > Especially when you knowledge base getting big. > > > > It's also hard to follow the evolution of the DB, since you don't see the > > changes like you do with flat files, as they change with CVS commits. > > New and significantly revised entries could be sent to the list, both > to be proofed by area experts and to act as sort of a "FAQ a day" > update to people learning about different sections. Don't want to > drive list traffic up, but hey. Hmmm, sonder if a mod_perl FAQ a day > list would make sense. Kinda your one-a-day Vitamin MP. This is a hard issue. A. If you create a new list, most of the people won't get on it, because they don't want extra traffic. I assume that this list is not only for sending the Q&A items, but discussing them as well. B. If you do this on the main list, people will get unsubscribed, because of the heavy traffic. I guess we could have modperl-daily-faq list ala [EMAIL PROTECTED] (which is mainly dead). But this doesn't solve the problem of where the FAQ items are to be discussed. Another problem is how to avoid overlapping with the book/guide like materials. In http://perl.apache.org/guide/troubleshooting.html I've solved this mostly by listing the symptoms only and linking to the portiongs of the guide for the explanations. Having the knowledge base disconnected from the main material will make this duplication removal and maintance overhead very hard. > > I think I need more convincing points to decide to make it as DB. > > I think the biggest points are to make it easy to submitting "articles" > and encourage near real-time peer review, along with structured > searching. What's the problem to submit articles right now? You want something to be added to the guide, submit to the list, get peer review, get someone to store the cleaned version in the guide, then update the DB. I still prefer to have it flat, while easily convertable to any flexible format imaginable. The idea of throwing many items into DB simple doesn't work, because many records in this database will want to preserve some order between them. For example look at the most disconnected items in the troubleshooting chapter. I've the items sorted by 'configuration', 'build', 'startup', 'run time'... categories, so you can easily narrow your search, by jumping to the right section. I don't say you cannot do this with DB approach, but then it gets complicated as you lose some of the flexibility. In any case, as long as we build the knowledge base in a way that can be easily converted from one format to another without doing any manual adjustments, we can fine tune things as we go. I'd hate to find things n
Re: knowledge base - was Re: RFC: mod_perl 2.0 documentation project
On Tue, 7 Aug 2001, Jim Smith wrote: > On Tue, Aug 07, 2001 at 10:16:26PM +0800, Stas Bekman wrote: > > > Just some pseudo-random ideation boiling down to "let's use mod_perl > > > to buils a knowledge base" both to demonstrate it's power and to serve > > > the community. > > > > I like the idea!!! > > If we can come up with a proposal for a generic knowledge base product that > would be useful in an IT environment, I can probably devote some of my work > to it -- this is something I've been wanting to put together at work for > customers and our help desk people but haven't had time yet to get it all > together. I'll have more time in September after the students return. go ahead and be the first to propose Jim :) _ Stas Bekman JAm_pH -- Just Another mod_perl Hacker http://stason.org/ mod_perl Guide http://perl.apache.org/guide mailto:[EMAIL PROTECTED] http://apachetoday.com http://eXtropia.com/ http://singlesheaven.com http://perl.apache.org http://perlmonth.com/
Re: RFC: mod_perl 2.0 documentation project
On Tue, Aug 07, 2001 at 10:16:26PM +0800, Stas Bekman wrote: > [Barrie, I hope you don't mind that I put it on the list, the more people > contribute the better the outcome :)] Not at all, I just noticed that others seem to have replied directly and followed suit. > > Something like this: http://perl.apache.org/guide/troubleshooting.html ? That's what made me think of it. That deals with a lot of the common ones, I was thinking of something more open-ended that would grow to contain more symptoms and (where useful) more details on how to fix things. For instance, including the failures found in a lot of systems would mean covering various tempalting system failures. One of the great things about Perl and mod_perl is the diversity, but it's also daunting to newcomers to identify all the peices and what might be wrong, especially in a troubleshooting situation. > The problem with DB, is maintence. When it's flat, people read mostly > sequentially, point out and fix problems. When it's in the DB, most of the > items would hardly come up and it's easier to have stale data in there. > Especially when you knowledge base getting big. > > It's also hard to follow the evolution of the DB, since you don't see the > changes like you do with flat files, as they change with CVS commits. New and significantly revised entries could be sent to the list, both to be proofed by area experts and to act as sort of a "FAQ a day" update to people learning about different sections. Don't want to drive list traffic up, but hey. Hmmm, sonder if a mod_perl FAQ a day list would make sense. Kinda your one-a-day Vitamin MP. > I think I need more convincing points to decide to make it as DB. I think the biggest points are to make it easy to submitting "articles" and encourage near real-time peer review, along with structured searching. > > Hmmm, since you've already pointed out that printability is not the > > primary goal, I wonder if we should just take AxKit and it's nascent CMS > > and start building a knowledge base? The book format is nice for > > getting spun up to speed, but the knowledge base interface is what might > > actually cut down on list traffic. > > Well, if you don't get to work with XML directly. I sure thing dislike > maintaining simple documenents in XML. Since you have to use some web > interface to edit the documents, you have no power of editors like > vi/emacs, which makes the work much harder. I don't care about the underlying format, make it a POD variant if you like. > > I could even see a search interface on an email address, so when you > > see a FAQ pop up on-list, a simple forward to [EMAIL PROTECTED] or > > something would do a search and send you back a message suitable for > > forwarding to the original poster or something. > > This would be a very sensitive change. You don't want to AI replies end up > on the list, since they won't be correct all the time. I would suspect that the reply might be a URL for the user to follow. Probably 20% of all questions on-list are answered by you or Perrin or others zinging a URL to the relavant section of the guide. Can that part of you be augmented by an AI? > > Kinda like the IRC bot purl. > > Heh, I'd love to play with infobot (==purl) in the real world. I think > Kevin said that it's ready for working outside IRC. :-). > Sure, there is no limit on how the third book should look. As long as it's > manageable and useful for users. The first two books will play it strict. > The third one is very flexible. Agreed. > Yup, exactly. seems very exciting if actually get to implement it. Then > the world domation will be finally a next chapter. :) The winners get to write the history books ;-). - Barrie
Re: RFC: mod_perl 2.0 documentation project
[Barrie, I hope you don't mind that I put it on the list, the more people contribute the better the outcome :)] > Hi Stas, sorry it took so long to get back to this :-/. it's not late al all, really ;0) we have years to come to work on this project. > Some minor feedback. I could see an additional "books", a > troubleshooting reference (as opposed to a guide, like part VI). Many > service organizations have large manuals that are essentially a > compendium of failure modes and instructions for how to troubleshoot > each one. Seems like a searchable database of error messages, etc. > might be a boon to the community. Given some keywords or a message, you > could find (in one query) articles in the db *and* mailing list messages > related to them. I could see the usual knowledge base type rank this > article. Something like this: http://perl.apache.org/guide/troubleshooting.html ? The problem with DB, is maintence. When it's flat, people read mostly sequentially, point out and fix problems. When it's in the DB, most of the items would hardly come up and it's easier to have stale data in there. Especially when you knowledge base getting big. It's also hard to follow the evolution of the DB, since you don't see the changes like you do with flat files, as they change with CVS commits. I think I need more convincing points to decide to make it as DB. > Hmmm, since you've already pointed out that printability is not the > primary goal, I wonder if we should just take AxKit and it's nascent CMS > and start building a knowledge base? The book format is nice for > getting spun up to speed, but the knowledge base interface is what might > actually cut down on list traffic. Well, if you don't get to work with XML directly. I sure thing dislike maintaining simple documenents in XML. Since you have to use some web interface to edit the documents, you have no power of editors like vi/emacs, which makes the work much harder. This doesn't mean that you cannot split the flat files into items and have a parallel interface for search. In fact Matt has already done this. Since http://perl.apache.org/guide/troubleshooting.html is all simple items, it's very easy to itemize it. Also don't forget the split version of the guide, used by the search engines: http://perl.apache.org/guide/index.html#search > I could even see a search interface on an email address, so when you > see a FAQ pop up on-list, a simple forward to [EMAIL PROTECTED] or > something would do a search and send you back a message suitable for > forwarding to the original poster or something. This would be a very sensitive change. You don't want to AI replies end up on the list, since they won't be correct all the time. But if you only reply to users, humans will still reply, so what's the point :) May be having posts like: WARNING !! !! THIS IS AUTOMATIC GUESS IT CAN BE WRONG ! But definitely an idea to consider and explore. > Kinda like the IRC bot purl. Heh, I'd love to play with infobot (==purl) in the real world. I think Kevin said that it's ready for working outside IRC. One of the cool things I thought about is replace Doug's presentation 'command server' protocol with 'infobot' loaded with mod_perl factoids. This will make the presentation even funnier, and we can actually put the bot online for others to re-use! > The other "book" would really be a set of how-tos for getting various > systems (templating engines, CMSs) up and running. That's probably a > lot like your C.IV, but the "howto" format has become a meme with a lot > of understanding in the community. Sure, there is no limit on how the third book should look. As long as it's manageable and useful for users. The first two books will play it strict. The third one is very flexible. > I guess I really see this as more of a "mod_perl guide plus knowledge > base" implementation than a "three volume book set", with the > pumpkings being "series editors" for knowledge base articles, and the > pumpkins could easily drag in "tech editors" from the appropriate > systems if need be. Yup, exactly. seems very exciting if actually get to implement it. Then the world domation will be finally a next chapter. :) > Just some pseudo-random ideation boiling down to "let's use mod_perl > to buils a knowledge base" both to demonstrate it's power and to serve > the community. I like the idea!!! _ Stas Bekman JAm_pH -- Just Another mod_perl Hacker http://stason.org/ mod_perl Guide http://perl.apache.org/guide mailto:[EMAIL PROTECTED] http://apachetoday.com http://eXtropia.com/ http://singlesheaven.com http://perl.apache.org http://perlmonth.com/
Re: RFC: mod_perl 2.0 documentation project
On Mon, 6 Aug 2001, Jim Smith wrote: > On Sat, Aug 04, 2001 at 08:12:25PM +0800, Stas Bekman wrote: > > This is a proposal for the mod_perl 2.0 documentation project. > > Sounds good. > > > + each project will have its pumpkin which will make sure that all > > chapters of the project adher to the same style, avoid duplication, > > etc. > > > > + inside each project, every chapter will have its own pumpkin, whose > > responsibility will be to maintain the documentation of the given > > chapter. Other contributors will delegate their patches to the > > chapter pumpkins and the latter will incorporate the changes into > > the document. > > > > + I'll start as the doc pumkin for the whole project and all > > sub-projects and will seek to delegate the sub-projects to other > > folks, as I won't be able to cope with such a big beast anymore. > > I think we might need a pumpkin that can cross-reference sections. For > example, Session management under Mason might go under Mason or Session > management. Whichever part doesn't have the text needs a reference to the > one that does. (A topic that came up recently on the Mason list.) This is > more of a benefit to people that are not familiar with the mod_perl > universe and can cut down on fruitless searching. If it isn't > cross-referenced, it probably is either not there, or hidden so deeply that > it needs to be pointed out by someone. > > Basically, this would be someone responsible for the `See Also's at the end > of each section, article, or what-not. That way, the chapter and project > pumpkins can concentrate on their parts of the whole and not feel that they > have to constantly be watching everything else. Sure. The intention for the guides to deploy hypertext features, and do lots of internal linking inside every guide and between the guides. This of course makes it hard to read the printed material, but I don't think we can do much about this. Unless we decide to build a fully fledged publishing system, without adding a huge overhead of using TeX or similar things used in real publishing. _ Stas Bekman JAm_pH -- Just Another mod_perl Hacker http://stason.org/ mod_perl Guide http://perl.apache.org/guide mailto:[EMAIL PROTECTED] http://apachetoday.com http://eXtropia.com/ http://singlesheaven.com http://perl.apache.org http://perlmonth.com/
