[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Request for comments: prettify snippets page

From: Graham Percival
Subject: Re: Request for comments: prettify snippets page
Date: Fri, 28 Dec 2007 08:09:29 -0800

On Fri, 28 Dec 2007 10:51:30 +0100
John Mandereau <address@hidden> wrote:

> Le mercredi 26 d__cembre 2007 __ 07:06 -0800, Graham Percival a
> __crit : 
> > I'm honestly not certain that this tradeoff is worth it -- even
> > disregarding the amount of work involved.  What problem(s) is this
> > supposed to solve?
> For example, t'd be a good thing to build a single
> Texinfo document (with .itelys) for all snippets, so we could easily
> get a single PDF and a single with all snippets sorted by categories
> (this is a user request IIRC), and a set of HTML pages with one
> category (or tag) per page, with easy navigation (we have this, but
> with no easy navigation); to achieve this, we should not use
> subdirectories.

Easy navigation could be achieved by spending 15 minutes editing

The single PDF would be nice, and the HTML pages would be
identical to what we have already.  So the end result is a slight

> I'm ready to work on makefiles, and to
> achieve this.  I think it's much more reasonable that my previous
> proposal, what do you think?

Yes... but...

I hate to be a wet blanket (I'm fond of this phrase: "the person
who stops other people from having fun"), but everything that I've
learned about documentation project management is screaming "not
worth the effort".

- the HTML would be identical to what we have already
- the current system works.  It wastes about 1 Kb of disk space /
  git tracker space.  If anybody cared about that, I bet I could
  save that much space by removing old comments from vocal.itely.
- it takes... what, and extra minute for building the docs?  Maybe
  5 minutes?  Again, IMO this is a minor issue.
- this would require changing LSR.  In my experience, any change,
  no matter how simple, takes at least one month.  While we're
  waiting for that change, you'll have a whole bunch of modified
  files in the build system ready for the new stuff, and I'll
  still be using the old build system.
- it would require $NO_CLUE amount of time and effort from you to
  implement the new system.
- it would require another $NO_CLUE amount of time and effort from
  you in $NO_CLUE weeks, after LSR has been updated, to fix/tweak
  the system.

If I were to add this to the GDP technical-todo list, it would be
in the MEDIUM section.  In other words, there are about 10
technical things that would improve the docs and which I am not
going to do, which are more important.  (and easier to do!)

If you can prove me wrong -- get Sebastiano to change LSR in two
days, whip up the python scripts in half an hour, and have
everything beautifully working before the new year -- then great!
But all of my experience on the docs and snippets suggests to me
that this will be a lot more work than you think.  :|
I therefore feel obliged to point out all the problems, in order
to potentially save you a lot of time/effort/frustration.

- Graham

reply via email to

[Prev in Thread] Current Thread [Next in Thread]