Re: Outline for Author's Guide

[Kendall Clark <kclark@ntlug.org>]

>>>>> "Tim" == Tim  <tjbynum@wallybox.cei.net> writes:

    >> What kind of tools? I think preparation of the AG should
    >> precede working on tools. We really don't want people moving to
    >> DocBook until the AG is complete and they can follow it. I'm
    >> also not sure what tools need to be created, other than perhaps
    >> doing a linuxdoc2docbook mass conversion to give pre-existing
    >> authors something to start from.

    Tim> I think a set of minimal tools should be in place with the
    Tim> guide for 1) using DocBook and 2) converting existing
    Tim> LinuxDoc to DocBook.  I do not at this time want to see any
    Tim> type of migration from LinuxDoc -> DocBook by any of the
    Tim> authors at this time.  I am only making suggestions on what
    Tim> should accompany the Guide when it's given to the
    Tim> authors/maintainers.

Ok, I guess I don't agree. There are tools for using DocBook: (X)Emacs 
and nsgmls and DB itself is all you need. There already is a DSSSL
script that converts from LD->DB. *There are other people already
working on making this stuff "easy" for authors.* I.e., it may not be
proceeding as quickly as some want, but it isn't an unadressed issue.

Putting together an AG is, however, not being addressed at all, at
least not until the last few days with the formation of this
committee. It seems to me, then, that we should focus on the AG as a
primary deliverable, especially since it can be used w/out
super-nifty-tool-bundles, but super-nifty-tool-bundles w/out the AG is 
likely to lead to chaos, i.e., every single LDP author doing their own 
thing with DB and thus negating the benefits of LDP using DB to begin
with.

That's my argument, not my preference or mere opinion.

    Tim> I personally do not see the Author's Guide without them nor
    Tim> do I see the tools without the Guide.

    Tim> Yes, I agree that we can write a script to get all the
    Tim> current docs created, but I also think that allowing the
    Tim> authors to do this themselves would be a nice beginning
    Tim> point.

Really? Well, we can disagree about that, but in either case it's not
strictly the business of this committee, imho. We should stick to
formulating policy for how the LDP is going to use DocBook. The tools
issue and the migration issue both need to be addressed; but they
should either be addressed by other committees, or by this committee
only after the AG/usage issue has been addressed.

I'm not trying to be argumentative, but I think this is something we
should have some consensus about here. I'll repeat my view just to be
clear: there are already people working on the other issues; no one is 
working on the AG. It should get priority here.

    Tim> This is not a chicken/egg question.  I would just like to see
    Tim> they both go hand-in-hand.  Could just be a personal opinion
    Tim> on my part and I'm perfectly willing to listen and/or change
    Tim> my mind if there is a need.

Yeah, I don't disagree with your points, just the priority of them. As 
I see it, there are four issues in migrating to DB:

1. upgrading the tools
2. content work (actually getting docs from LD -> DB)
3. DB usage guide
4. author education.

(1) and (2) aren't perfect, but there is *something* that's been done
or being done now to address them by other groups/people. No one as of 
yet has done anything about (3).

So, again, I propose that (3) be our primary, first deliverable, and
that we lend a hand to working on (1) and (2) only after (3), if at
all. As for (4), Norm Walsh's book being online is a great help in
solving it, and together with (3) should be all that authors need to
use DB effectively.

I've made my position clear, I suspect, so I'll not say anything more
about this issue. I do think, however, that however our agenda is
decided, we need to make sure to decide it and make the decision
explicit. It will be helpful to know what we're about in this
committee, at least so we can have some boundaries to help keep
ourselves on track.

One way we can proceed is just to poll the people on this list to get
some idea about which of the 4 areas of DB migration they want to work 
on (or some issue not listed yet). If there is significant agreement,
then we have our answer. If there isn't, we can break up into smaller
workgroups and pursue things that way, though I suspect this committee 
is already pretty small, so that splitting up might leave us with a
few *pairs* of people. :>

Best,

Kendall


--  
To UNSUBSCRIBE, email to ldp-docbook-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org