[docs] Re: [interchange-core] Server hosting future ...

[Dan Browning]

At 05:56 PM 10/9/2002 +0100, you wrote:
> > > I think it is time to restructure the docs. I really, really, don't like
> > > the way it is done, because every time the doc changes (inserting a
> > > paragraph or removing one) the URL to the item changes. I don't quite
> > > know how to solve that problem, and don't quite know how others
> > have solved
> > > it in the past. Maybe it can't be easily solved with the granularity we
> > > have.
> >
> > If we could assign a unique identifier to each section, like a hash key,
> > that could remain constant despite section reorganization, or if a section
> > is removed altogether, the header and a link to a relevant area could
> > remain.
>
>I also thought this. This is what I did with Helpem structured document
>management; each section and each image object have unique references.
>Document sections are then constructed into a tree, with the ability to
>re-include sections within a section if necessary.
>
> > However, it would take some work to hack that into SDF.
>
>I know very little about SDF. Is there some sort of comment tag which could
>be used for this?
>
>I see the lack of image support within the IDR documentation as a downfall
>too.

Actually, images are supported via {{IMPORT:foo.gif}} or inline html:

!block inline
  <img src="foo.gif">
!endblock

We just haven't used it yet (I tested it a while ago though, and as I 
recall the images were put in PDF/HTML format, but not TXT, etc.).

> > > My suspicion is that redoing the docs is beyond the part-time efforts of
> > > anyone. There are so many of them and in such different states of repair
> > > it would be a full-time job for 3 months to whip them into shape. No one
> > > here has that kind of time, I suspect.
> >
> > I agree. It would be a serious amount of work to make any kind of impact
> > other than incremental improvements and fixing obvious errors.
>
>Personally, I have found the use of SDF and CVS as a bit of a hurdle to
>editing the docs. Helpem is based upon Wiki markup, in fact Helpem was born
>out of my frustrations over its poor structuring and image support. Whilst
>it has its own extension of Wiki markup to learn, I find it quite
>straightforward (and fast) to update the documentation for the various
>little applications that come with Webmaint hosting using the web interface.
>
>Given that I too recently resigned, in my case from a nice secure job as
>Group Information Systems Manager of a UK plc company, I hope to have more
>time in the future to devote to such things. I the short term I am still
>juggling two jobs as I work my notice on a reducing number of days over the
>next four months. Once I am full-time Webmaint I hope I can put as much in
>as time as I see other people doing.
>
>Back to the point.. SDF doesn't look like a great way to structure and
>manage a large document. If the source was in the database imho it would be
>easier to maintain, and may open up the management to a wider group. A tree
>structure allows easy reorganisation as a document grows. I find this suits
>my method of documenting things particularly well :-)
>
>Obviously there is the issue of generating the other formats to consider. I
>use <htmldoc> in Helpem, I have not looked at other conversions although I
>will be coding the output of plain text soon, and probably a static html
>tree. Both of these have been asked for by the WinPT user/developers.
>
>Do people here want to stick to SDF as the document source or is it time to
>reconsider the position?
>
>Jonathan.

I like SDF because it is so Perl-ish, but it is too bad that it doesn't 
really have a user group associated with it anymore (our CVS is the only 
location for recent SDF docs that I know of).  However, I'm not stuck on it 
and I would be open to considering other formats.  If there is another 
format that would really open the door to more contribution, that is a fact 
worth considering as well.

--
/~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\
| Dan Browning, Kavod Technologies      <dan.browning@kavod.com> |
| (360) 882-7872 x7, 6700 NE 162nd Ave, Suite 210, Vancouver, WA |
\~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~/
Software, n.:
         Formal evening attire for female computer analysts.