Document organization
Kevin Dangoor
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
Ronald Jaramillo
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.
Managing prev-next reference on a document basis quickly becomes a
mess ( you still need some kind of index overview to see which
documents are linking to which)
And what about the references themselves? Say we have document A and
B. A is the first document B the second. Should we add this
information to the A document in the form of a next link or to the B
document in a form of a previous link or both places (uarggh)
Should we then enforce that only one doc can have a reference to
another one?
Cheers.
Ronald
________________________________
Ronald Jaramillo
mail: ronald AT checkandshare DOT com
blog: http://www.checkandshare.com/blog
Kevin Dangoor
>
> 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.
Kevin
Ronald Jaramillo
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. This could be regular
versioned file called docudo.index.
An as you suggest there are several ways we can make index management
suck less.
Cheers
Ronald
Kevin Dangoor
> 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
Kevin Horn
Or do you want to set it up?
Kevin H.
Kevin Dangoor
I've got it part of the way there. I don't think I'll get a chance to
do the rest today. Feel free to go for it, if you wish. (It was
getting a pysvn error, so it's possible you may not be able to fix it
without root... if you can't get it to work, I'll take a look Monday)
Kevin