Menu
▾
▴
firebird-docs
|
From: Mark O'D. <mar...@lu...> - 2001-02-04 21:40:12
|
Hi Helen All sounds pretty good stuff, and it's sounds like some sort of solution to our documentation conundrum. I think the linux documentation uses the SGML suite of tools. I looked at it a but, but not much. They generate html, ps, txt versions from the source. Bill would be good to get involved, I understand he had a lot of his own stuff anyway that could help. On the sourceforge stuff, they seem to be over their initial growth pains, and are a bit more reliable recently. Depending upon how you go it might be worth useing, CVS is pretty good at distributed development, and that seems to be how this is also going to work. Cheers Mark Helen Borrie wrote: > Hi All, > > Recently, folk have started rumbling about documentation, which is > GOOD. Bear with me while I brainstorm a little here... > > 1. A radical plan which is formulating in the green, greasy depths of > my mind is to give up on the IBDH project - not because it aint great > (we REALLY need that book) but because it's financially out of reach > for me to do it as planned. However, for a developer book, its > outline is good - the result of many eyes and hands. I have more > stuff to add to the outline - ideas continue to come through - so that > I think we have the bases pretty well covered already through > community effort. > > With the permission of my translators (who are a good and rational > bunch, for sure) I would like to transmogrify the IBDH project into > the Firebird Documentation project. > > A bonus in this might be that I/we can persuade Bill Karwin to come > aboard such a project, now that the angst has subsided. Bill himself > outlined an ambitious Open Document project for documenting IB, from > all angles. I would be willing to take on the role of manager/editor, > much as I planned for the IBDH. It would be so much the better for > Bill's participation. > > 2. At the time the IBDH was conceived, it was in the context that ISC > was planning to publish the updated IB 6 manuals. We could change the > content and organisation of material in Ann's publication-ready > version radically to circumvent copyright restrictions. The rewriting > and re-editing of the content would be well within my range. There is > no copyright on the intellectual content of these docs. In my view, > the IB6 Manuals' organisation is still very poor. We could kill two > birds with one stone by reusing the ISC work in a revised, expanded > and more user-friendly documentation set. > > 3. As to format... I'm one who likes to have a well-indexed book on > hand in preference to anything in electronic format. There are lots > who agree with me; and just as many who prefer helpfiles, html, PDFs > or whatever. The "infrastructure" of the IBDH was on track to store > all the content in a database and apply various processing tracks to > it to enable output in many formats - hard-copy drafts, print-ready > copy, HTML, Linux How-To, etc. Obviously the means to this end is XML > and Unicode. If we can persuade all contributors to submit material > in plain text Unicode, we can keep things open for alternative outputs > to suit whatever requirements arise. > > 4. Incorporating the sourcecode development stuff...we need to get > this under some form of version control, I think. I certainly have > provision for it in the IBDH database structure. If we can have a > server somewhere that is dedicated just to documentation, I believe we > can do some good management and version control that doesn't suffer > from the vicissitudes of Sourceforge. They do it in the Linux > projects and IMO it works well. > > Well, just some embryonic thoughts... > > Helen > > All for Open and Open for All > InterBase Developer Initiative · http://www.interbase2000.org > _______________________________________________________ > > _______________________________________________ > Firebird-admin mailing list > Fir...@li... > http://lists.sourceforge.net/lists/listinfo/firebird-admi > n -- Your database needs YOU! http://firebird.sourceforge.net |
|
From: Andy C. <an...@ad...> - 2001-04-24 10:10:23
|
I brought up the documentation issue in firebird-devel and the result = was the issue has moved to the firebird-docs list at sourceforge. I cannot get through to www.interbase2000.org so I can't check your = reference. I feel that Firebird documentation is seriously crippled and needs work. = I hope to participate in creating a good documentation facility for it. = I want to help create a "Reference Manual" slash "User's Manual" that is = dynamic and inclusive. The best documentation available for Firebird, the Beta Docs, are all = tied up in copyright issues. Apparently Borland won't let us extend and = update those docs to cover both InterBase and Firebird. If this is true, = I will help document Firebird and let Borland pay for documenting = InterBase. What I wish for is not so much a printed manual as a web site where the = divisions of the "manual" correspond to subtrees on the site.=20 The whole thing MUST be globally searchable; the second worst problem = with Borland's documentation is that you have to figure out, on your = own, where Borland stuffed the information. The worst thing about = Borland's documenation is that we don't have any way to correct it when = it's wrong. Being a web site, this can not only can cover the material like a = manual, but it can include links to other documents either here or on = other systems - FAQ's, papers, various "Documentation" pages, etc. With = a little effort it can be a reference library and not just a manual. Being browser based, it can be burned into a CD-ROM. There's talk that the source for this web site Firebird manual should be = in the CVS tree at Firebird. That make sense to me. There's talk about = it being in Docbook; I'll have a look at that.=20 Significantly, however, I want to get away from the classical model = which is documenation professionals writing everything. There is so much = work that we must go towards an open source model where anyone who knows = something can check out the relevant portion of the 'manual', update it, = and check it back in. The level of mandatory review is not yet clear. To restate, what I want as a first cut is a web page user's manual tree = of the topics, in name covering the material in the beta docs but in = practice all the pages will be empty until somebody has the time to = write them. There will probably be one higher level which functions as a = documentation library, with one link into this web page user's manual = tree. If you, or anyone, can pry something loose from Borland it would help. = Even the docs for InterBase 3 would be a help. If you want to work with = me, if you want me to work with you, say the word. One way or another, = we should do this on the Firebird-Docs list. ----- Original Message -----=20 From: "Joseph Alba" <ja...@il...> To: <fir...@li...> Sent: Monday, April 23, 2001 23:35 Subject: [Firebird-devel] Documentation Hi to all Interbase newbies and devotees. This is Joseph Alba of the = Interbase documentation (see www.interbase2000.org). I would like to take your = views on how the Interbase documentation effort should begin, and how we should = go about it. My goal is to have a weekly beta on the documentation. All who want to contribute and comment are invited to write me privately at my email = address ja...@il... As I mentioned to Helen, my experience as an independent developer makes = me careful about job specification, scope, and definition. I would like to = deliver a documentation set that is NOT an exhaustive tome of Interbase, but = rather, what Interbase users would want and need. So, all suggestions and comments are welcome and needed. Please help. = And please reply in private to my email address Thanks, Joseph Alba ja...@il... |
|
From: Andy C. <an...@ad...> - 2001-04-25 01:24:10
|
A: As much as possible of this discussion should be fed through = Firebird-docs, yes? Seems to me that people perceive Firebird-develop as = development=3Dcoding, and don't want it cluttered up with documentation = issues. But if you and I rely on direct e-mail we have no community.=20 B: We need to think about what source format. DocBook has been = recommended; I read up on it last night and it's not bad but then again = I haven't got it executing yet. THREE QUESTIONS: > 1. What do we want? We want documentation for Firebird; available via the Internet, globally = searchable, accurate, up to date, maintained. For me, appearance is = secondary. Electronic version is critical, print version is secondary. I = think of the term "User's Manual" but conceptually the target is = everything you need to know about FB. > 2. What do we have? We have a number of very busy people who know everything, and a large = number of people who know a little bit. We have pretty good = documentation which we can't copy but we can read. We have very good = articles about various "side" issues. > 3. Can we do what we want with what we have? Certainly. There's a critical speed/time trade-off; the more people we = can suck into this engine the faster we'll get ofr the ground. Because of the distributed nature of our knowledge, I think it's = critical that we encourage Ann, Boris, Claudio, David, etc. to correct = things without having to install any software or learn any conventions. = The people who know the most are the most busy; we must find an = efficient way to tap their brains.=20 > I'd like to do things the Linux way. If you want something, try = starting it > and send it to me. I'm not familar with "the Linux way". I thought that the open source way = was to create a pool and encourage people to contribute. But whatever.=20 A few days ago I volunteered to have the tin can tied to my ankle; now = Joseph Alba has taken the tin can and tied it to his ankle. You're = welcome to it. You will be the caretaker for the Firebird Documentation. = When formatting issues are settled, please create the outline - source = for editing and web site for reading. Then the rest of us will start = filling in the stubs. Is this a good plan? Is it how you see your role? ----- Original Message -----=20 From: "Joseph Alba" <ja...@il...> To: "Andy Canfield" <an...@ad...> Sent: Tuesday, April 24, 2001 22:11 Subject: Re: [Firebird-devel] Documentation > Dear Andy, > Thanks for your comments. Helen B. informed me that Doug has a lot of = load > right now, so, I should take up the cudgels for documentation. > Right now, I'd like to be more specific with what must be achieved. I > believe in the maxim that in any new undertaking, ask yourself 3 = questions > 1. What do we want? > 2. What do we have? > 3. Can we do what we want with what we have? > What we have is a community of volunteers. Gleaned from your = suggestions, > among those what we want is are Reference Manuals and Users Guides = that is > not copyrighted by Borland. (Other suggestions are How To's collation, > etc...) > I'd like to do things the Linux way. If you want something, try = starting it > and send it to me. For the community, I will assume that you will not = claim > any intellectual rights to the product, and I will assume the right to > correct and revise it and present it to the community for further > corrections. Everything will be Open Source with Firebird Community = having > the last say. If somebody else wants to improve on it, they send me = their > revisions. > I will have a website where you can download the beta docs. Really = like the > Linux Documentation way. > So, Andy, if you have something in mind, start writing it and send it = to me, > so I can go over it and present it to the community. > By the way, don't worry about my credentials. I was asked by Helen and = Ann > last year to play second fiddle to Doug. But now, they told me to get = things > going. > Thanks a lot for your enthusiasm. I'm looking forward to your = contribution. > Have a great day! > Joseph Alba |
|
From: Andy C. <an...@ad...> - 2001-04-25 17:47:13
|
> Actually, I did not take the tin can.=20 When Helen / Ann / Jim / Pavel want to know what's going on with the = documentation, who are they going to ask? You. That means you've got the = tin can. Being the person that everything is routed through, you're the = only one who knows what's going on, you're necessary to hand out tasks, = you've got the tin can. You put yourself in the prime spot, so you're = it. That doesn't mean that you have to do it all; it means that you get = the flack, the questions, the worry, the gold star. > One pressing need is to have a Firebird documentation that is not 70% = lifted > from the Interbase version. One idea I'm looking into is to use the = other > database servers' documentations as guides and outlines, while putting = in > Firebird instructiosn. If we don't run into copyright problems with those other sources, yeah.=20 > I really thank you for volunteering to help. It would be neat if you = can > give me the topics (or titles) you would like to work on, so I don't = have to > duplicate those areas. (I believe in delegation and teamwork.) In order for there to be delegation there must be a boss. That's you. Here's my list: Connections - I'd like to work up coherent coverage of connections. I = can't handle some of the UNIX / NT details but I think I can cover the = commands, the mechanisms, the rules and the guidelines. SQL Language Reference - This is the massive part. While I tend to write = pretty good specifications, which this is, essentially, I may not know = all the ins and outs. But for the Firebird group it may be easier for me = to write it and others correct it than to wait for others to have the = time to write it. If you've got a more qualified candidate hand it to = her. The isql tool - In my outline this goes in a section including gpre, = gbak, dli, etc. I use isql a lot and I'd like to cover it. What I get = wrong know can be altered later. > I hope you won't mind doing this on a private e-mail conversation = first. By > experience, I can assure you that this is a lot better because we can = thresh > out difficult ideas and express ourselves more freely without inviting > flames from others. When things have settled down to a pretty level = field, > that's the time we go public. I hope that's okay with you. If we were in a company I'd have no trouble with this. I would go to the = boss to make confirm that you are authorized to do this and that I am = assigned to take direction from you. However, in Firebird there is no = central authority and so there is no one who can say "Yes, Andy, do it = his way." In Firebird the community is the authority. You tell me that = Helen told you, but Helen didn't confirm it to me, and even if she did I = don't know to what extent I should be taking directives from Helen. The = one person I have heard enough about, and enough from, to respect = personally is Ann. If anyone in Firebird has the authority to tell me = "go there", it is Ann, and she has it because I gave it to her. I'm going to send this directly to you and I expect that you will be = sending things directly to me. However, I am also going to post this to = Firebird-docs so that the community, who in effect is our stockholders, = has notice and record of what is going on.=20 |
|
From: Joseph A. <ja...@il...> - 2001-04-25 23:47:56
|
> That doesn't mean that you have to do it all; it means that you get the flack, the questions, the worry, the gold star. By experience, the community does not give flak or pass blame around. In my view the gold star is for the community. > Here's my list: > > Connections - I'd like to work up coherent coverage of connections. I can't handle some of the UNIX / NT details but I think I can cover the commands, the mechanisms, the rules and the guidelines. Just write about it, and indicate in parenthesis things that you want to be added but are not familiar with. If I know about it, I'll write about it or if not, somebody else will. > > SQL Language Reference - This is the massive part. While I tend to write pretty good specifications, which this is, essentially, I may not know all the ins and outs. But for the Firebird group it may be easier for me to write it and others correct it than to wait for others to have the time to write it. If you've got a more qualified candidate hand it to her. > > The isql tool - In my outline this goes in a section including gpre, gbak, dli, etc. I use isql a lot and I'd like to cover it. What I get wrong know can be altered later. > By the way, have you downloaded the 10mb references of Interbase? What ever we do, we should be careful NOT to copy anything from this, otherwise, all our efforts will go to waste since the community won't be able to freely use it. Thanks for you help. Let's get going. Have a great day. Joseph Alba ja...@il... |
|
From: Andy C. <an...@ad...> - 2001-04-26 12:58:07
|
> > Connections > > SQL Language > > The isql tool > Just write about it, and indicate in parenthesis things that you want = to be > added but are not familiar with. If I know about it, I'll write about = it or > if not, somebody else will. I shall do so. I will also send you preliminary versions; I welcome your = comments, suggestions, and guidance. I won't worry about format for now; = you can probably read anything I can create and, worse comes to worse, = you can cut and paste. > By the way, have you downloaded the 10mb references of Interbase? If you are referring to the Beta Documentation, I downloaded that last = autumn when I started with Open Source Interbase. IMHO it is reasonably = complete and well written, but it suffers from copyright restrictions = and lack of a global search. When it's incorrect there's no legal way to = fix it. Ann is supposed to be putting the updated unreleasable version = where I can download it so that I can learn. I also have all the HLP = files from the autumn download of InterBase (for reference, not for = copying). > What ever we do, we should be careful NOT to copy anything from this, > otherwise, all our efforts will go to waste since the community won't = be > able to freely use it. No mechanical copying. No deliberate mental copying. Ideas are = necessary. For example, AFAIK, Borland owns copyright on the only = documents that say what the Firebird SQL syntax is. ANYONE who writes = down what Firebird accepts for the CREATE TABLE command syntax must have = learned it from Borland copyrighted material, because it does not exist = anywhere else. > Thanks for you help. Let's get going. Yo! __________________________________ http://www.laonet.net/AndyCanfield |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X