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

[Mike Heins]

Quoting Jonathan Clark (jonc@webmaint.com):
> > > 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.

You can do images. We just don't.

> 
> >
> > > 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?

Insofar as it would be very difficult and laborious to convert what
we have, we want to stay with it. 8-)

Personally, I would now go with Docbook if I had a choice. It is supported
by lots of tools and has become somewhat of an open-source standard.

Still in all, it is the content that matters most. 

-- 
Mike Heins
Perusion -- Expert Interchange Consulting    http://www.perusion.com/
phone +1.513.523.7621      <mike@perusion.com>

Function in chaos, finish in style. -- Unknown