--- Joern Nettingsmeier
<[EMAIL PROTECTED]> wrote:
> Nunez Steve wrote:
> > Gentlemen,
> >
> > May I suggest that before you remove that warning,
> > consider upgrading the documentation just a bit.
> >
> > I've been struggling for weeks now to implement a
> > simple rework of the default authoring environment
> to
> > use CSS instead of tables, without success.
>
> geeez. i hate the table stuff as much as the next
> guy, but to actually
> tackle that - respect. are you sure you know what
> you're getting into?
>
> friendly advice: ignore the ugliness, it's just the
> authoring interface.
> you can still create beautiful, table-less websites
> in live. we should
> postpone that until after 2.0, since it's largely
> cosmetic. and it's a
> huuuuge undertaking, given how messy the styling is
> atm.
That's probably good advice. At the moment, I have no
idea what I'm getting into. I tried everything I could
based on the documentation I have, and am now just
trying random ideas -- obviously not the best way to
proceed.
Since the live site is really the most important, I
think I'll take your advice and give up on authoring,
provided I can get live working and live with the
table driven page styling.
> [snip]
> what kind of documentation do you miss most?
I suppose that there are two parts to the
documentation 'problem':
1. Overlap with 1.2 - it's not clear from the wiki
what is applicable to 1.2, what is only applicable to
1.4 and what applies to both.
2. A documentation roadmap of sorts. Whilst all of the
bits of documentation might be present, they're bloody
hard to locate. Some time spent reorganizing and
cleaning up existing documentation would be very
useful.
> [snip]
> i'm thinking of putting a "getting started" kind of
> howto into the wiki,
> describing how to build, create a clean slate for
> succesful custom
> publications and do the necessary tweaks so that the
> server does not
> explode due to excessive caching and logging. would
> that help?
That would be very helpful, especially the custom
publication part. Tuning isn't as important, rather it
is only important once you have something to tune and
in production.
> [snip]
> we're
> trying to remedy that by ruthlessly cleaning up the
> code base, but there
> are still some utterly confusing legacies left. when
> you try learning
> from the wrong piece of code, your life will be
> miserable.
We're in a similar situation ourselves, where we are
preparing a code base for maintenance by a different
team of people in the future. I recently reviewed a
piece of code that I wrote nearly 8 years ago that was
only intended as a temporary measure; yet there it was
all these years later, still being used: undocumented
& poorly written. If anyone coming in were to have
read that they would certainly have been confused and
gone down the wrong track, and this was an important
piece of functionality. It's too easy, once you learn
how everything works, to just leave it as it is.
To state the obvious: clean up, removing legacy code
and a focus on documentation of code is a worthwhile
investment. It makes contributions, bug fixes and
enhancement easier, especially for any newcomers to
the project.
Regards,
- Steve
____________________________________________________________________________________
Shape Yahoo! in your own image. Join our Network Research Panel today!
http://surveylink.yahoo.com/gmrs/yahoo_panel_invite.asp?a=7
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
