Date: Sun, 22 Aug 1999 22:55:21 +0100 From: Nik Clayton <nik@freebsd.org> To: Satoshi - Ports Wraith - Asami <asami@FreeBSD.ORG> Cc: "Jordan K. Hubbard" <jkh@zippy.cdrom.com>, Nik Clayton <nik@FreeBSD.ORG>, doc@FreeBSD.ORG Subject: Re: Default FDP docs installation directory? Message-ID: <19990822225520.A73959@catkin.nothing-going-on.org> In-Reply-To: <vqc7lmoksk8.fsf@silvia.hip.berkeley.edu>; from Satoshi - Ports Wraith - Asami on Sun, Aug 22, 1999 at 03:39:35AM -0700 References: <1171.935316202@localhost> <vqc7lmoksk8.fsf@silvia.hip.berkeley.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
Hello again Satoshi. My apologies once more to the members of -doc.
On Sun, Aug 22, 1999 at 03:39:35AM -0700, Satoshi - Ports Wraith - Asami wrote:
> Trust me, I don't like it very much either. I would very much like to
> stay out of this and pretend nothing is happening, especially since
> I'm not that involved in the Japanese translations anymore.
>
> But I read the grumblings in the Japanese mailing lists from those who
> have to do the actual work, and can't help but notice that they've
> been yanked around by chains for months.
Am I reading this right, or are you not actually speaking for the Japanese
doc team at the moment.
If you are, then that's fine. But if you're not, I'd like to stress again
that I'd really, really, *really* like to hear from the Japanese team,
and in particular from Jun Kuriyama.
> The Japanese doc team has been forced to do a lot of extra work
> because of all these conversion and reorganization work.
In case it's escaped your notice, so has the English, Spanish, Russian, and
Chinese teams. And the French team has been waiting in the wings for
something like 6 months now waiting for this work to be completed before
I pull in their translations -- I didn't want to bring in a large chunk of
newly translated docs immediately before a big repository change, as it's
needless bloat.
This is manifestly *not* the Japanese team being forced to do a lot of
work that none of the other teams have to do, and at no point in the
discussion that preceeded the change (to the best of my knowledge)
did anyone from *any* of the translation teams stand up and say
Sorry, can we postpone this change please. We haven't got the manpower
to dedicate to it right now.
One message like that from any of the translation teams would have been
enough to stop the repo change dead in its tracks.
> Just tonight I tried to fix the japanese/handbook port and gave up after
> I couldn't get it to work after a few iterations of ja -> ja_JP.eucJP, en ->
> en_US.ISO_8859-1 type substitutions. That makes me think, why do I
> have to do this?
Good question. Possibly because it's part of ports/, and you're the ports
wraith. I seem to recall various kludges and workarounds going in to some
of the doc/ Makefiles to try and detect when some of the
> When I do a massive reorganization in the ports tree, I make sure I
> fix things that break myself or at least sign up people I can trust
> who will fix it quickly after I change something. Most of the time,
> the changes go through at least a couple of iterations of full package
> builds to make sure everything works ok.
Sounds about right.
> That's part of being a manager on a volunteer project. If he doesn't
> want to do this, that's fine, but then he shouldn't be making
> decisions.
Uh, Satoshi, I am doing it. I built and rebuilt the docs numerous times
on my local system and on freefall. I posted several requests for people
to download the latest trees and give them a hammering on their system
before I unfroze the tree and turned the website building back on.
I've spent God alone knows how much time writing the e-mails and the plans
for this. I wrote the FDP Project Primer, which is there exactly because
I wasn't going to do the conversion without ensuring there was good
documentation backing it up. That's 94 pages of documentation right
there. Where did you think it came from?
I'm writing the DaemonNews articles that are slowly demistifying the
doc/ and www/ make(1) Makefiles. I'm proposing and encouraging new
committers to the FDP, one of whom is shortly going to commit his SGML'ed
"Committers Guide" to the tree, so that life is made even easier for
new committers.
I'm answering stupid questions from people about how they get sections
in the HTML output to be numbered.
Getting new software to work on FreeBSD is quite a sexy job, with lots
of plaudits for those people that do it. Writing and maintaining the
documentation and the infrastructure for that documentation is much less
exciting work. I'm not about to start arguing about which of the ports
teams and the doc teams do more work, but I am 100% satisfied in my mind
that we pull our weight, thanks.
> * do good work ripping into one another leaves the audience rather
> * unsure of how to react, and those being ripped into don't much enjoy
> * the experience either. I think this has all come about through
> * misunderstanding rather than malice and if people are getting "angry"
> * then they already need to go take walks before coming back and
> * attempting to communicate in public. We are all experienced enough to
> * know the poor results generated by angry posts.
>
> People have been perpetually angry, that's all.
I haven't had an angry e-mail from Jun Kuriyama yet. I'm sitting here
with a lop-sided grin on my face wondering what on Earth you're going to
come up with next.
> * Nik has just put in a large amount of work here and I would like to
> * just return our attention to that fact for a moment while those who
> * don't like his methods attempt to make it sound as if there was
> * nothing good about the conversion or reorganization work. There was a
> * lot of necessary work done here, from both a tools and a content
> * standpoint, and if the look-and-feel isn't spot-on the first iteration
> * or two, well, that's easily evolved. I'm also sure that Nik has no
> * intention of leaving tools for formating the various translations
> * broken, considering how much work he's put into packaging the
> * translations in a more flexible fashion lately.
>
> I hope I'll see evidence to support your point soon. Right now I
> honestly can't say the doc tree (especially the Japanese part) is in
> better shape than before.
It's in about the same shape as before -- I'd say it's a little better
than it was, but only marginally. However, we have almost all the LinuxDoc
docs out of the tree (the Russian FAQ hasn't been converted yet, it's a
mechanical job, and if I don't see patches to do it soon I'll get on to
it, and there are two English primers that haven't been converted).
We have a build system that massively reduces its reliance on the files
in src/share/mk/, and will become even more separate from that shortly.
We have the beginnings of infrastructure in place to support making packages
of all the documentation, in all the languages. This will simplify
"make release" considerably, although probably not in time for the 3.3
candidate.
We have the beginnings of XML support ready to go in to the doc/ tree.
We have people working on a proper, extensible, DocBook -> *roff
converter, something that people on other mailing lists have been
clamouring after for years.
We have people actively jumping at the chance to maintain the FAQ, which
is a pleasant change.
Yes, we've just expended a lot of energy to go from one position to what
looks like being a very similar position.
But the view from our new position is radically different.
> * I think this is simply yet another communications break-down, perhaps
> * on both sides, and there's no reason to accuse Nik of lying or
> * otherwise being anything but *confused* about how much communication
> * had or had not occurred.
>
> I asked him something and he gave me quite an explicit answer. Maybe
> he was confused. Then why didn't he didn't clalify that point when I
> requested names, I have no idea.
Lack of time. Here's an average day.
7.00am Get up
7.05am Start downloading the overnight mail
7.10am Jump in the shower
7.40am Leave for work, with laptop, carrying last nights mail
7.50am On train. Spend ~ 1 hour researching and replying to mail/code
9-13.00pm Work
13.00pm Lunch. Spend more time researching and replying to mail/code
14-18.30pm Work.
18.30pm Travel home. More mail/code
19.30pm Collapse for an hour or so
20.30pm Upload the replies written during the day, commit changes
written during the day.
2.00am (Yes, really) Sleep
On Tuesday's I play badminton (badly, but it gets me out of the house),
Thursday nights are social drinking nights, and weekends are claimed by my
girlfriend (unless she's away).
That's probably more detail than you really wanted. But if you can see a
space in there for "Grovel through 7.8MB of mail looking for one specific
message written some time ago" I'd like to see it.
So yes, sometimes it takes me a while to reply. And yes, sometimes, I
might not put enough detail in to the messages that I write -- I've noted
this comment, and I'm working on acting on it.
But, you'll all be happy to know that there'll be considerably less e-mail
emanating from this part of the world in the very near future, as I fully
expect co-authoring "Teach Yourself FreeBSD in 21 Days" for Macmillan will
take up a great deal of my e-mail time. But rest assured I'll make the
time to devote to the FDP.
> Also, the thing that really pushed me over the edge is that Nik claims
> he's only one of us and is not the "manager" that people think he is.
> This has been patently false as far as I can tell, and it's really
> unfair to label those who oppose him as Don Quixotes fighting an
> imaginary dragon.
I'm striving desperately for analogies here.
In an earlier message I listed a long group of people in the FreeBSD
project that I'm not. I might have been wrong about that, and, if
you'll forgive the hubris, perhaps my role is (or certainly should be)
more akin to David Greenman's architect role.
From what I've seen David is more than happy to delegate work out to
those people that actually want to do the work, and rarely needs to get
involved directly (I could well be understating David's involvement here,
I don't follow the lists he haunts too closely, but it's been a while
since I saw a commit message with "dg" in it).
Obviously I haven't got the balance of David's personality traits yet, but,
then again, he's got a few years on me.
That architectural role is perhaps a better fit for what I'm trying to do
here.
How does the following patch to handbook/staff/chapter.sgml strike
everyone?
Index: chapter.sgml
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO_8859-1/books/handbook/staff/chapter.sgml,v
retrieving revision 1.55
diff -u -1 -r1.55 chapter.sgml
--- chapter.sgml 1999/08/11 13:53:13 1.55
+++ chapter.sgml 1999/08/22 21:51:28
@@ -698,3 +698,3 @@
<varlistentry>
- <term>Documentation Project Manager</term>
+ <term>Documentation Project Architect</term>
> Oh, and please don't tell me to go take a walk. I've sat on the
> previous e-mail for 2 days, even playing golf (now that's a long walk)
> in the process. It didn't change my opinion. :)
Golf? Try horse riding. Then you can join Jordan, myself, and anyone
else interested, if we manage to go for a trek during FreeBSD Con.
N
--
[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?19990822225520.A73959>