Date: Sun, 22 Aug 1999 22:14:07 +0100 From: Nik Clayton <nik@freebsd.org> To: Satoshi - Ports Wraith - Asami <asami@freebsd.org> Cc: Nik Clayton <nik@freebsd.org>, doc@freebsd.org Subject: Re: Default FDP docs installation directory? Message-ID: <19990822221406.A80051@catkin.nothing-going-on.org> In-Reply-To: <vqcemgwm9q1.fsf@silvia.hip.berkeley.edu>; from Satoshi - Ports Wraith - Asami on Sun, Aug 22, 1999 at 02:43:33AM -0700 References: <19990818121931.A4266@kilt.nothing-going-on.org> <19990819131224.A844@kilt.nothing-going-on.org> <vqcemgwm9q1.fsf@silvia.hip.berkeley.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
[ I'd dearly, dearly love to be able to say that I've redirected all
followups to this message to the freebsd-navel-gazing list. Unfortunately,
we don't have one, so it's stuck here in -doc. I'd quite like to take
this to personal e-mail, but I can hear the chants of "Why won't he
discuss this in public? FreeBSD is too cliquey, we want to know what's
going on!" ringing in my ears, so I haven't. My apologies.
But, if you're reading this for the humour value, take my advice and go
straight to the last page -- there's a corker waiting for you. ]
On Sun, Aug 22, 1999 at 02:43:33AM -0700, Satoshi - Ports Wraith - Asami wrote:
> * I get the impression that some -doc subscribers have the wrong idea about
> * what it is that I'm doing as the Doc. Proj. Manager, and what my role
> * actually is.
> :
> * But in doing this, I'm no different from any other contributor to this list
> * (well, every contributor that's also a committer, and I'm pleased to report
> * that the number of FDP related committers is growing nicely at the moment).
>
> So you are not the one that makes the decisions when people don't
> agree? That's good to hear. :)
That depends :-)
I'm trying hard not to have to make specific decisions, because I'm trying
to make sure that there's enough discussion that the right choice falls
out of the discussion. As I said in the previous message, some times
there are no obvious right or wrong choices to make, and it's only when
people start asking questions in the discussion that pointers to the right
answer come up.
Having said that, I get personal e-mail every day from people who read -doc,
both committers and non-committers, asking whether they should do 'x' or
'y', and I answer them as best I can. Where possible I cc: my replies
back to -doc so that (1) my response gets in the archives, and (2) people
who might know more about it than I do can respond if they see the message.
Sometimes I can't answer the question at all, and just point them at people
who I hope can answer the question.
And I imagine that one day there will be two committers who both want to
commit different variants on the same change, and I'll get asked to choose
between them. But as I say, I'll try and *not* say "Do it this way!",
but I'll ask questions about both approaches to see if one way is better
than another.
> I had the distinct impression that you are the manager that we need to
> convince, and you are a very hard person to convince once you make up
> your mind (which is usually very early). I guess I was wrong.
Yeah. I don't normally take a lot of convincing if something's a bad
idea. Take the "/usr/local/share/doc/fdp/" thing. That was discussed,
and turned around in roughly 24 hours.
*24* hours. That's practically no time at all, particularly when I do
all my e-mail reading in blocks of time that are roughly 12 hours apart.
(i.e., at t+0 I post the message, at t+12 the first responses have come
in, some making points that I'd considered, which I responded to countering
those points, some making points that I hadn't considered, and I start
thinking "Hmm, maybe this isn't such a great idea", and t+24 more responses
have come in, almost all of them pointing out problems, and I drop the
idea.)
Notice, incidentally, that I don't just drop the idea, but I say so
publically, and in a message to the list, which means that this all gets
archived. I'm not interested in trying to hide mistakes that I might
have made.
> * To try and illustrate this, lets look at three different examples from the
> * relatively recent past:
>
> There's another one. You converted the documents from Linuxdoc to
> Docbook, arguing it's better. Honestly, I still don't see why it was
> necessary.
These are in no particular order of significance;
1. LinuxDoc is dying. SGMLTools, the main 'wrapper' around it in the
Linux world has switched to DocBook, and the Linux Documentation
Project is moving towards it (although not as quickly as we have --
this is mostly because we have less documentation to convert).
2. DocBook is a far better designed DTD. Yes, there's more to learn
about it (which is why I wrote, and continue to write, the primer),
but it's more extensible, more flexible and more widely supported.
3. DocBook as a DTD promotes consistency in the choice of markup. This
is a good thing, as it (a) makes the job of marking things up easier,
(b) allows more consistency in the output, giving a strong sense of
'family' between the documents, (c) prevents the author having to worry
about what their document will look like, and instead concentrate on
marking up their documentation accurately.
4. DocBook is a "richer" markup model, so our documents will be easier
to downgrade to other markup models (like, for example, HTML, or
PilotDoc).
There are others, and I suspect that there's about to be slew of messages
from DocBook supporters, so I'll wait and see what points they make, before
following up with anything they've missed.
> The few documents I care about (handbook's ports chapter)
> is much harder to read in HTML after the conversion with all the
> numbers gone from the section headers.
Edit freebsd.dsl, and put this code fragment;
(define %section-autolabel%
;; Are sections enumerated?
#t)
somewhere between the
<![ %output.html; [
and
]]>
markers. Then take two aspirin and call me in the morning if the problem
persists. If people think that should go in freebsd.dsl shipped by the
FDP then say so -- I'm agnostic about the issue, but if people want it
in then it can go in.
What you're describing is an issue with the formatting, which is (unlike
LinuxDoc) much removed from the markup language itself.
Yours is the first time I can recall seeing anyone on this list mention
this as being a problem -- note that I'm not saying it's the first time
anyone's mentioned it, but it's the first time I've noticed it as a
problem.
> The sgml files are harder to edit too, but that might be because we've
> been using Linuxdoc for a long time.
Harder to edit how? You've got a consistent set of indentation for the
first time, making it much easier to see the structure of the document?
And if you mean that DocBook is hard because you don't know DocBook then
I'd appreciate comments on the Primer so that I can improve it for people.
> Also, the Japanese PS and PDF handbook generation is still broken
> since the Linuxdoc -> Docbook switchover.
It is? Define broken? I know that there were problems, but I was under
the impression that Jun Kuriyama had fixed them, updated the port, and
forwarded them on to Norm Walsh.
> Is anyone going to fix that?
They will if you let me know what they are. A quick
% cd /usr/gnats/docs
% grep dsssl *
didn't show up anything, so I guess people don't care enough to send in a
PR about it. I can't fix stuff (or at least, investigate) stuff I don't
know about.
> I'm not saying you should fix it, but since you are the one
> that proposed the switch and the one that implemented it, you should
> at least make sure you have someone signed up to fix it (ideally
> before the switchover).
It's obviously escaped your attention, but I am doing stuff to fix it.
People commented that they didn't like the way the FAQ was coming out. I
had a patch back to the list within 12 hours or so -- so far, just one
person has bothered to comment on it. Since they said they liked it, it's
gone in to my queue of things to commit -- it'll take a few days, because
I've mailed my patch back to the original author for comments, because I'm
not convinced my patch is the right way to do it.
> * One thing that should be made clear -- just because it was committed as
> * such does not mean (and should never mean) that I'm not flexible in
> * changing it at the first opportunity as necessary.
>
> That's good to hear. But to avoid any further misunderstandings,
> please don't commit things if it's already surrounded by controversy.
At that point it wasn't surrounded by controversy.
> * For the future, I'm going to try and make sure that my suggestions are
> * marked as such (and not "commandments handed down from the Doc. Proj.
> * Manager"), so that they're less likely to cause what seems to have been
> * some offense.
>
> Then it might help if you don't post messages with subjects like:
>
> Resolution: FDP reorganisation
>
> right when the discussion started. That's called pushing the wrong
> button.
I think you might have a loose SIMM somewhere. The "Resolution" message
was posted after we'd already had one long round of discussion on the topic,
and two posted drafts of the plan for doing it. I thought that after the
amount of time it had been discussed every objection had either been
discussed, and realised that it wasn't a problem, or discussed, and
incorporated in to the plan. It was only after the "Resolution" message
was posted that a set of fresh problems and concerns were raised.
More specifically: my first message was posted on 4th May (subject line
was "doc/<lang>/books/*, doc/<lang>/articles/*, and docs.freebsd.org".
That discussion had 4 distinct contributors, and carried on until the 15th
May. It slowed down over the last two days, so on May 13th I posted a
revised version of the plan, with the subject line "FDP Directory
Reorganisation". People seemed to wake up at this point, and we carried
on until June 26th. During that discussion I was amending and posting
amendments to the plan as we went along, and as with the previous
discussion, it petered out towards the end, which is why I posted the
"Resolution" message in June 23rd.
You might think that a message posted in June 23rd to a discussion that
was kick-started on the 4th May is "right when the discussion started",
but I've got a hard time following that train of thought I'm afraid.
This thread devolved in to three main discussions:
1. The first was about the name of the Japanese directory. I'd
mistakenly thought that the Japanese consensus was for
ja_JP.EUC-JP. You bought the fact that I'd made a mistake about
this to my attention, and I immediately changed it the ja_JP.eucJP
you requested. That's a non-issue.
2. The merits of repository copies, whether or not commit histories
needed to be maintained, and the tags. I was quite happy to let
this discussion carry on without much input from me -- I didn't
completely follow the points the Japanese team were making, didn't
have much time to, but trusted that between yourselves and JDP you
would come to an arrangement. As far as I can tell, it was all
resolved amicably.
3. The third, and by far longest sub-thread was sparked by Motoyuki
Konno, who asked why we were doing this at all. This then triggered
a re-run of large chunks of the two earlier threads on this, with
the same arguments back and forth.
> Then there's the matter of trust (as a human being). Honestly, there
> is very little trust in you, especially among the Japanese people.
Christ, I've offended a whole nation :-)
OK, seriously, for a moment: if you felt the need to write that then
something has gone seriously wrong. I'd like to hear from the members
of the Japanese Doc. Proj. (in private mail please, not withstanding the
disclaimer at the start of this message, I don't think we need to subject
-doc to the rest of this) so we can discuss this a little more slowly and
a little more calmly. I mean no offense to you Satoshi, but until this
little blow-up my contact with the Japanese translators was Jun Kuriyama,
and he's been conspicuously absent from this thread.
I'm also going to commit the third cardinal sin of e-mail discussion
netiquette: I've had private mail from members of a couple of the other
translation teams asking me what the hell is going on here, and why are
we getting so uptight about this, so there's at least some remnants of
trust left lying around.
> I asked you twice about who in the Japanese translation team you talked
> to about the FAQ Docbook conversion. Will you please answer my
> question?
Sorry for the delay. Going through 7.8MB of outgoing mail file takes
some time, particularly when you have to spend so much of that time
writing long and involved e-mails to mailing lists because some people
just won't let some issues wither and die.
Jun Kuriyama, personal e-mail, subject line "Re: FDP Directory
Reorganisation", message ID
<19990607235712.A35217@catkin.nothing-going-on.org>
It was in one message to Jun, talking about plans for after the
conversion. With hindsight I think it's clear how Jun could have ignored
it, or put it on the "to think about later" pile, and not got around to
it.
The error is still mine.
> If I don't get an answer this time, I will assume you lied the first
> time around and in fact didn't talk to anybody on the Japanese team.
I love comments like this in e-mail. It always leaves the recipient in
such a dilemma.
Should I delete it, and pretend I never saw it?
Should I rise to the bait, start foaming at the mouth, and flame you
with 15 screenfulls of invective?
Should I instead try and pick it apart, refute it at length, bore the
audience with carefully argued debate.
Should I just make fun of it?
I just can't decide.
Tell you what, since this is the new happy, shiny, FDP organisation, where
consensus rules, I'll throw this one out to the assembled masses. Hey
guys, if you're reading this, and you've got a strong opinion as to which
of the options above I should take (or if you've got a new one) please
e-mail me directly and let me know. I'll summarise the responses back to
the list (unless, of course, most of the responses are "No, please, stop
talking about this, we're very bored of it, and would just like to get
on writing some documentation in peace and quiet please.").
Cheers,
N
PS: Oh, one more thing. I'm going to be over for FreeBSD Con. in
October, and I understand that some of the Japanese translation
team are going to be there as well -- could we maybe postpone this
whole thing until we can sit down and talk about it face to face?
I'm a lovely guy in person, willing to stand my own round of drinks,
and I can probably bore you all with pictures of my girlfriend.
PPS: I wonder if there's any statistical correlation between the
fluctuation in length of my e-mail messages and the times that
my girlfriend spends on holiday.
PPPS: OK, seriously for a moment again. "Jun Kuriyama". Am I right in
using "Jun" in the same way other people would refer to me as "Nik",
or have I got it backwards? I've asked about this before, but I
think it got lost in the noise, and the last time the topic came up
(on another mailing list as it happens) I don't recall any clear
consensus -- thanks.
--
[intentional self-reference] can be easily accommodated using a blessed,
non-self-referential dummy head-node whose own object destructor severs
the links.
-- Tom Christiansen in <375143b5@cs.colorado.edu>
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990822221406.A80051>