On Mon, 2 Jul 2001, Rob S. wrote:
> > I'm not sure I understand that. There are plenty of HTML editors, and 99%
> > of the people on this list know a bit of html. Nobody asked for "good
> > looking" documentation or cool formats, the content is missing.
>
> Agreed, but using Note/Text/Whatever/Pad is what the majority of people end
> up using because WYSIWYG editors have a tendency to butcher the resulting
> HTML for the next poor sap to come along and edit it. <insert years of
> notepad versus wysiwyg editors debate>.
Not all, and even if they do - the problem is we don't have good
documentation ( content or aspect ), not what editor is used. If you
submit a good doc I'm sure we'll be able to "tidy" it, reformat it, etc,
regardless of your editor. We all know html and have a favorite editor.
> As well, nobody's *asking* for good looking docs, but if someone's willing
> to put in the time and effort (e.g. myself), what else can it do other than
> help? ;) It's possible to have better-than-average-looking docs with a few
> well-chosen colours, etc. without burdening the build with images.
Than do it - as you can see there aren't too many people working on this
area, so nobody should be able to complain if you choose one editor or
another ( there is a nice rule to use - "if you don't like it, do it
yourself" :-).
> I fully agree with the reorganization since right now there isn't
> really any - aside from appdev having its own subdirectory. I'm not
> sure I understand the reasoning behind making the docs part of the
> ROOT (or /doc) web-app. I imagine to make them accessible from the
> default Tomcat homepage? How un/important is that? Either way, like
> I mentioned before - organization decision, not a doc author's =)
Well, apache is doing exaclty that. Most people don't read the /doc
directory, but if they see a link on the first page they might do so.
But since I'm not working on the documentation I realize my opinion
doesn't matter as much as the doc author's preference ( since he's doing
the work :-)
> Right now if you look under the Struts repository, you'll see that all of
> the documentation is *.xml, and I imagine the build is responsible for the
> transformation... I guess we'll have to talk to them to see how all of that
> is working out - what's the motivation?
As I said, the content is more important. Having a format that is known by
all the people ( html ) is IMHO very usefull.
If we can't get people to write documentation in HTML using any of the
existing editors, I guess it'll be much harder to ask them to learn a
XML DTD ( especially since the dtd is used only in apache, while the rest
of the world is using the docbook ). And of course, force them to use
notepad instead of wysiwyg ( even if docbook has some editors, they are
either incomplete or too expensive ). Add to that the "generation" step (
where you compile the xml to see how it'll look in html ).
Costin
