Re: Suggestion for CG - make targets section

[Graham Percival]

On Tue, Aug 17, 2010 at 07:45:33PM +0100, Ian Hulin wrote:
> Firstly, what's the grown-up doc developer's way of this without having
> to kick off your make doc run and then leave it going overnight every
> time you notice a typo in the doc source?

Grown-up developers read the "known issues" under "building
documentation" in 3.6.2.  Or they ask the doc meister.

> Secondly, wouldn't it be really useful to have a section 3.5.5 in the CG
> which lists all the useful make targets and tells you what they're for?

No, because:
1) there's too many of them
2) some of them are broken
3) we don't know what they all do
4) we don't know which ones are broken

> Maybe we can collect these in this thread and, if somebody answers the
> first question, I might be able to face writing the new CG section.

Emergency fixes only.  It's just not worth trying to explain the
build system.

> P.S. If this information is already easily available please don't try
> and sound too snotty or smug in your reply :-) .

I was forced to sit through over six hours of postgraduate
presentations from engineering.  Judging from the quality, most of
the time it was their first presentation.  And first attempt at
making slides.  Also, my background is in computer science, so I
don't have a clue what a MOSFET transistor is, so most of the
talks were over my head.  Also, the stupid conference was booked a
15-minute coach ride away, I suspect precisely to force
postgraduates to sit through the entire thing (although many
people left during the day, and the organizer -- despite
repeatedly sending emails about the "COMPULSORY postgraduate
conference" didn't seem to care).

I mean, seriously.  If you decide to highlight (in red) five words
out of your (I'm not kidding) 62-word "abstract" that you put onto
your slide, you've already REALIZED that all the audience really
needs to read is five words.  So just give them the maoing five
words and cut the rest!

If the desire was to actually help students learn how to prepare
slides and give presentations (which seems to be desperately
needed), rather than simply appeal to some government funding
agency requirement, it would be *much* better done in small
increments (say, 1 hour per week, over the first 8 months of your
degree), where students get feedback about their slides and
presentations.  But this setup is just ludicrous, and is very
obviously simply ticking off a box for external demands to produce
"better speakers", without any kind of care about doing a proper
job of it.

... and yes, there's another whole day of this tomorrow.


Anybody who has a thin skin should killfile my emails for the next
48 hours or so.

- Graham