[docs] xmldocs - docelic modified 7 files

Jon Jensen jon at endpoint.com
Tue Nov 30 14:29:44 EST 2004


On Sat, 27 Nov 2004, Davor Ocelic wrote:

> I was just experimenting with stuff, and I probably checked it in
> not thinking that anyone would go investigating what I did :)
> (I change two computers so it's easier for me to check in the CVS than to 
> drag current work with me on CDs).
> 
> So actually, the whole block of text you commented on wasn't actually
> supposed that anyone sees it; I always experiment like this, then let it
> consolidate in my mind to see which points are valid and which need to go.

Ah, ok. Normally we don't use our CVS repository like that -- we only 
check in work we consider finished. But I guess you've been the only one 
using the xmldocs repository so far, so had free rein. :)

> Well, if we keep iccattut simple, then even after reading it people are
> not able to take on harder stuff (let alone the foundation/standard catalog).

That was fine, according to the original idea of the document. Everyone 
assumed you had to use one of the demo catalogs, and we wanted to show 
that you did not, and help distinguish Interchange core from the demos.

> I had an idea of turning iccattut into a strongly-guided document that
> shows all principles and logic behind constructing *usable* catalogs.
> Furthermore, I had an idea of *slightly* raising the technical level - 
> if the reader can't get his ImageDir properly - then chances are they
> won't be able to follow the tutorial anyway - no matter how simple 
> we make it. (And SecureURL is not a problem - I put the same value as
> for VendURL in the example).

It's not that I don't think ImageDir should ever be discussed, but that I 
wanted to go step by step, never introducing anything that isn't 
explained. That meant, for me, leaving out fluff like images when we're 
trying to just cover the basics.

> In my vision, iccattut would also be expanded in length, so that you
> can look at the Standard demo after reading it and feel like you know
> what's going on there.

As I said, that's a different vision than we original authors had. But I 
think your envisioned tutorial would be of greater value, and I can see it 
would be a pain to write a totally separate one.

Perhaps we can achieve both goals in this document by making it longer but
not complicating the beginning. That would allow me to go as far as I want
in learning, but not feel as overwhelmed by the beginning of the document
as many beginners do with all the other IC documentation, where you often
have to understand everything to understand anything.

> Also, why I mention stuff like trackfile etc.? Because I believe in this
> principle of expanding user's views by giving little implicit examples
> (I waste no explanation on them, and it's still clear from the example
> what the stuff does).

I think it's better to not show *anything* beyond what's necessary. IC
is too complicated to newcomers, and this is the only document that is
aimed at helping them get over the hurdle. I want every little bit of
detail possible in the reference docs, of course.

> > I'd like to see the ITL explanation be *extremely* brief. There's a whole 
> > document, ictags, that explains this stuff in detail. For now, can't we 
> > just get the user to *use* the tags simply, and follow our tutorial? That 
> > was the point.
> 
> I wanted to move the description out of ictags to iccattut, because the
> new "incarnation" of ictags are autogenerated reference indexes and
> there's no place for prose there. And whenever you want to point
> reader to this section, you can use like <olink doc=iccattut section=tags>.

I think that would be bad. Any of the reference guides that naturally can
be organized in alphabetical order should have all the details possible,
because it'll be easy to find later. The catalog tutorial IMHO shouldn't
be a reference. Once having read and understood it I should never have to
look at it again, because now I know what to look for in the truly
detailed reference docs.

Why can't we put prose in the autogenerated stuff? You had a way to do
that for configuration directives, right? I'd rather have the tutorial 
link to the reference docs than vice versa.

> > Any discussion of "proper" HTML and CSS is totally out of place here IMHO.
> 
> I have people asking me why iccattut uses tables for design, and also
> questioning whether it's because IC can't use CSS. Ok.

You could put in very simple CSS, but I wouldn't in any way discuss
whether it's better or not. There's certainly nothing "wrong" with tables
anyway; some data really is tabular. In the end, why can't we just use
very simple HTML and mention that in a real site you'd want to use some
CSS to pretty it up?

> > I'm feeling a bit protective of this document because I put so much work
> > into making it simple, and I don't like to see it get bogged down and 
> > complicated like all the other docs.
> 
> Well I thought we agreed (long time ago) to reduce the number of docs.
> So I wanted to put everything that's related to basic stuff in iccattut.

I don't think there really is much "basic stuff" in IC. What would it be?
There are only basic vs. advanced *explanations* of this big blob of
stuff. :)

> > I'm considering ripping out any RPM or Debian-specific stuff because
> > that's made a mess of it too. A tarball install in someone's home
> > directory would make it more standard.
> 
> Nah, that is solved by the profiles thing. If you build docs with "rh"
> profile, users only see values which apply to .rpms (and the same
> analogy for .debs and tarballs).

Ok. That would be better.

> I usually compare Interchange to similar "senior" free software projects
> out there - Amanda, Postgres, some MTAs, GRASS, etc.. I have a vision
> of how IC docs should look like to catch up with smaller and faster-moving
> projects which draw a lot of attention and popularity to themselves. 
> I also want to lower the "entry barrier" for the public. To be precise
> actually, I want to keep the barrier high - but do that by
> expecting users to do their share of preparation and homework, and not
> by deliberately omitting details and keeping users no more familiar
> with the software than they were before reading the documentation.

I think we have the same goal. I think the best way to reach it is to give
a gentle, but lengthy (I like your goal of lengthing the tutorial)  
introduction. And make the references docs extremely detailed and
accurate.

Since you've been doing all the work lately I'm not going to complain a
ton, but I just wanted to see if we could keep from complicating this
introductory document and change the direction a little. Don't let me slow
you down; I'm not going to nitpick your work to death. You're doing
excellent work.

Jon


More information about the docs mailing list