[doc] examples

[Thomas Cherryhomes]

Oops, I did a bad.. I really meant to post the former message to the list!

/me modifies his imp to put Reply to List as the FIRST option if available ;-p :-)

Anyway, you may have noticed that I started on a glossary in my SGML. I wasn't
able to finish it because I got called off on more pressing duties, however I do
think a glossary would be most beneficial seeing as not everybody knows what
IMAP is, or POP3, or a mail filter, .. ad infinitum.

can I contribute glossary material, as well?

-- 

|| Thomas Cherryhomes
|| OpenMINDS 




Quoting Eric Rostetter <eric.rostetter@physics.utexas.edu>:

> Quoting Thomas Cherryhomes <thomas@openminds.tv>:
> 
> > Well, based on my experience with writing documentation, it helps if there
> is
> > at
> > least a step by step instruction on a common use of an advanced topic (say,
> a
> > mail filter.), otherwise, how are novice users going to become power users?
> > :-)
> 
> Good point.  Have to balance size/space vs. empowering users.  Probably
> empowerment should win.  I'll conceed that point.
>  
> > > How much help do you want to do?
> > >
> > I would like to help out with content, seeing as this is what makes
> > documentation. We can worry about stylisation later.
> 
> Good.  I was looking at your html output before...  Sorry to say, it isn't
> so great.  Now I've looked at the pdf output, and finally the sgml.  There
> is more there than in the html output, so I will use more stuff from you.
> 
> Last night I "harvested" many of your images for use.  Not sure which I will
> use, but some of your screenshots should save me having to make my own, and
> some of your small icons are really nice!  I'll be working them in asap
> (though
> we have a small problem with our html translation in that it isn't including
> alt tags for images...  Need to fix that...)
> 
> > > Biggest thing right now in content.  The more the better...  Even just
> > > pointers to missing content that should be there is helpful!
> > >
> > This would call on a set of document guidelines divided into essentially
> two
> > structural parts:
> > (1) Content Structure (How should the mark-up in the document be
> structured?)
> > (2) Build Structure (How should the individual files making up the
> > source-code of the documentation be structured within the filesystem?
> 
> Yes, we need to create this still...  I'm still working it out myself as I
> go along (as the people doing this previous to me left almost no docs)
> 
> I'll try to get at least an outline together for this...  But it will be
> a document in progress to some extent.
> 
> > <opinion>For the record, I think using LISP to define a stylesheet is both
> a
> > good idea and a bad one. It's good in that they use a language with
> > relatively
> > few side-effects and a language that doesn't depend on the order of the
> > formatting material. It's bad that they chose LISP, a language with so many
> > parenthesis. XSL(T) isn't much better, they just replaced the parens with
> > tags.
> > :-)</option>
> 
> Well, I agree that XSL(T) is better.  But I didn't set up any of this...
> I'm just a content guy, who inherited an existing setup...
> 
> > However, I know that's what we have to work with. :-)
> 
> Or, I just ignore everything except the content/markup myself... :)
>  
> > Stylesheet material can be done independently of the content, and that can
> be
> > decided once we've created a consistent visual design for our
> documentation.
> > For now, let's put the meat on the bone :-)
> 
> Exactly!
> 
> > I will help out in anything I can (and when I can.. my life is a bit busy
> at
> > the immediate moment trying to get our first leg of funding.) I will pitch
> in
> > when I can..
> 
> Yeah, that's kind of the problem right now... Many of the core team is busy,
> myself included...  Bummer...
> 
> > What is the best way to submit content?
> 
> If it is small amounts, you can just submit to the doc@lists.horde.org list.
> Either post the content, changes, or a url to the content.  For changes,
> "cvs diff -u" is the best way to submit changes to existing stuff.
> 
> If you are going to do more substantial changes, we can set you up with CVS
> (write) access, and you can work in CVS along with me...
> 
> -- 
> Eric Rostetter
> The Department of Physics
> The University of Texas at Austin
> 
> Why get even? Get odd!