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

[Jonathan Clark]

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

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