> For linking purposes, and because we're using a WYSIWYG editor, it
> would seem to make sense to have individual pages be fairly small,
> rather than giant-sized documents. I'm thinking of the TurboGears
> Getting Started Guide (or even the 20 Minute WIki). These would be
> very large documents.

> What we need is a way to specify a group of documents as belonging
> together and what their order should be. That could be "next" and
> "previous" metadata entries on each document (somewhat cumbersome if
> the user has to edit it that way), or it could be some externally
> managed grouping construct.

> The other thing that would spring out of this is that it would then be
> possible to re-unify these docs into a printable form.

> Opinions?

> Kevin

> --
> Kevin Dangoor
> TurboGears / Zesty News

> email: k...@blazingthings.com
> company: http://www.BlazingThings.com
> blog: http://www.BlueSkyOnMars.com

> I still think that for software documentation an index manager makes
> sense.
> It's a PITA to maintain no doubt about it, but they are a great way
> to structure
> a document set. Furthermore you get previous - up - next links  for
> free, and they make it
> possible to export the docs into windows help format.

> A less structured approach could be to use category names to organize
> the documents.
> For example say you have the documents osx, solaris & linux all
> sharing the same category:
>   installing.platforms
> The system could treat them as siblings and provide next- previous
> links within the set.
> There is still a problem regarding the order of the documents.
> For the previous example, this is not an issue. But this won't work
> for pages in a tutorial.

> On 5/4/06, Ronald Jaramillo <ron...@checkandshare.com> wrote:

>> I still think that for software documentation an index manager makes
>> sense.
>> It's a PITA to maintain no doubt about it, but they are a great way
>> to structure
>> a document set. Furthermore you get previous - up - next links  for
>> free, and they make it
>> possible to export the docs into windows help format.

>> A less structured approach could be to use category names to organize
>> the documents.
>> For example say you have the documents osx, solaris & linux all
>> sharing the same category:
>>   installing.platforms
>> The system could treat them as siblings and provide next- previous
>> links within the set.
>> There is still a problem regarding the order of the documents.
>> For the previous example, this is not an issue. But this won't work
>> for pages in a tutorial.

> I think you're right on both counts, and this is kind of what I was
> thinking as well. For some documents, just listing them out by
> category is fine. For others, you want them to be indexed in some
> fashion.

> I think you're right that an index manager is the right way to go.
> Particularly because it seems reasonable to expect that a given
> document could appear in multiple indexes (making simple next/prev
> metadata entries too weak).

> Using an AutoCompleteField to add documents to an index and then
> something like a Scriptaculous Sortable to set the index order seems
> like a good strategy.

> The indexes should be stored on disk in SVN (since they're part of the
> documentation). They could probably be stored in ConfigObj format
> easily.

> On 5/4/06, Ronald Jaramillo <ron...@checkandshare.com> wrote:
> > I think XML it's ok for this. A simple unordered xhtml list will do,
> > and is still somethink you can view in a browser.
> > Element tree makes managing this quite trivial.

> Though you're right about ElementTree making this fairly trivial, I
> betcha it's not *this* trivial:

> In [3]:co = configobj.ConfigObj(unrepr=True)

> In [4]:co["index1"] = ["Foo", "Bar", "baz"]

> In [5]:co.write()
> Out[5]:["index1 = ['Foo', 'Bar', 'baz']"]

> ConfigObj is like a human-readable simple pickle...

> That said, I'm not picky at all on this point.

> > This could be regular
> > versioned  file called docudo.index.

> Yep.

> > An as you suggest there are several ways we can make index management
> > suck less.

> And suck less it will...

> By the way, I'm going to work on getting Docudo.org up soon and
> getting tg.org's docs ported to Docudo soon. The current situation is
> driving me batty and I want to turn off tg's Trac wiki asap.

> Kevin

> Or do you want to set it up?

> Kevin H.

>  On 5/4/06, Kevin Dangoor <dang...@gmail.com> wrote:

> On 5/4/06, Ronald Jaramillo <ron...@checkandshare.com> wrote:
> > I think XML it's ok for this. A simple unordered xhtml list will do,
> > and is still somethink you can view in a browser.
> > Element tree makes managing this quite trivial.

> Though you're right about ElementTree making this fairly trivial, I
> betcha it's not *this* trivial:

> In [3]:co = configobj.ConfigObj(unrepr=True)

> In [4]:co["index1"] = ["Foo", "Bar", "baz"]

> In [5]:co.write()
> Out[5]:["index1 = ['Foo', 'Bar', 'baz']"]

> ConfigObj is like a human-readable simple pickle...

> That said, I'm not picky at all on this point.

> > This could be regular
> > versioned  file called docudo.index.

> Yep.

> > An as you suggest there are several ways we can make index management
> > suck less.

> And suck less it will...

> By the way, I'm going to work on getting Docudo.org up soon and
> getting tg.org's docs ported to Docudo soon. The current situation is
> driving me batty and I want to turn off tg's Trac wiki asap.

> Kevin