My dilemma
Kevin Dangoor
1) It's designed to do exactly the kind of things with docs that I want
2) It's a TurboGears app (and I have a slight bias there)
And Docudo is close to being minimally usable (particularly after my
ReST fix). In fact, it goes beyond minimally usable in a couple of
areas (thanks to the group who got the ball rolling and Ronald for
adding on).
The problem, though, is that it's *minimally* usable. Very soon after
starting to use it, we'll undoubtedly want;
* anonymous users being able to edit and post "contributed" content
(I don't think that's quite there yet)
* spam protection of some sort
* ability for users to self-register
* ability to view old revisions
* handling of the "between versions" editing process
plus, others may want to use Docudo once they see its cool traits...
and they'll undoubtedly want help getting pysvn running (a
potentially non-trivial task).
The things that I listed there aren't really "gravy". They're
actually important tasks. They're not *hard*, but they still need to
be done.
Ronald is in the midst of a contract (plus ongoing work for others of
his customers). I have my hands full with another open source project
(plus I still have some finishing work to do on a certain book...)
While I was able to quickly hack in the ReST stuff, it occurs to me
that I'm not going to be able to follow through with the other things
that are required.
My real need is for a documentation tool for TurboGears with these
attributes:
1) editable through the web
2) versioned
3) able to include pictures
4) a reasonable way to separate documentation for different versions
of TG
5) a reasonable way to differentiate "official" and "unofficial"
documentation
I would also add an optional, but highly desirable, "full text
search" to that list. In addition, it would need those things that I
mention above as lacking in Docudo.
With the right set of plugins, I think I can get these things from
Trac. Trac has some other advantages (we currently have a bunch of
random content in a Trac that would require less conversion, and a
search of the trac will search over tickets, changesets *and* docs).
There may be other wikis that are better, though that's certainly
unclear. There are a lot of wikis.
I'm tossing this message out there in case someone wants to step up
and say "I'll take on Docudo! I happen to have 100 hours free right
now!" or "there's this other wiki that does exactly what you want".
Whatever the solution is, it's going to happen very soon.
Kevin
--
Kevin Dangoor
TurboGears / Zesty News
email: k...@blazingthings.com
company: http://www.BlazingThings.com
blog: http://www.BlueSkyOnMars.com
Karl Guertin
> I'm tossing this message out there in case someone wants to step up
> and say "I'll take on Docudo! I happen to have 100 hours free right
> now!" or "there's this other wiki that does exactly what you want".
> Whatever the solution is, it's going to happen very soon.
I seem to have lost svn access, but I'll take a look at it. Not sure
if I want to make commitments, but I really would like to see TG1.0
out and the mailing list active again. ;]
Kevin Dangoor
To be clear: Docudo's status is not going to stand in the way of
TG1.0. In fact, once I have some sane documentation tool/process up
things will move faster with doc contributions than Docudo code
contributions...
Kevin
Kevin Horn
However, I fin dworking on something totally different pretty therapuetic, so I'm hoping to be make at least _some_ contributinos in the coming weeks. That said, if docs are the main hold-up in gettng a 1.0 release out the door (and to my understanding they are) and we can use Trac for the moment, I say, why not? It's not the ideal solution, but as they say "the perfect is the enemy of the good." If it will speed things up on the docs front, I say use Trac for now and we'll use docudo fo rthe next TG release.
Kevin H.
BTW, did my question about extra lines being inserted in the ReST version of docudo show up in the list? I haven't seen it, but it's in my gmail sent items...has anyone else noticed a similar problem?
Kevin Horn
Sadly, the trac registration process stil isn't working, and I locked down permissions yesterday to prevent spamcapades from happening again, so you can't create or edit tickets without an account. Please don't be frustrated...we're working on it.
Kevin H.
Guy Hulbert
> BTW, people should feel free to look at the trac tickets at
> trac.docudo.org.
This is helpful.
>
<snip>
> "regular job", and we have an 8-week old in the house, so my
> time is a little tight as well. <-- (huge understatement)
Everyone's time is probably the same. However, I will try to put in a
few hours next week ...
<snip>
--gh
Kevin Dangoor
> I've just (today) started a contract myself, in addition to my
> "regular job", and we have an 8-week old in the house, so my time
> is a little tight as well. <-- (huge understatement)
>
> However, I fin dworking on something totally different pretty
> therapuetic, so I'm hoping to be make at least _some_ contributinos
> in the coming weeks. That said, if docs are the main hold-up in
> gettng a 1.0 release out the door (and to my understanding they
> are) and we can use Trac for the moment, I say, why not? It's not
> the ideal solution, but as they say "the perfect is the enemy of
> the good." If it will speed things up on the docs front, I say use
> Trac for now and we'll use docudo fo rthe next TG release.
>
I really appreciate all of the offers of assistance, and I think I've
worked out the details (haven't implemented them yet) of a good stop
gap approach. I'll set up a wiki with Moin Moin and a certain set of
plugins which will give us many of the benefits of Docudo (the big
thing that will be missing is the workflows we have in mind) and some
of the other cool things we would likely come up with given the focus
of the project. I'll set Moin up for ReST formatting. When the time
comes to switch to Docudo, the transition will be pretty seamless.
BTW, I'm aware that Trac can also use ReST. However, Moin has some
plugins and things that are more advanced than those available in
trac. Specifically, the hierarchical wiki bit. I'm planning to use
that feature to separate the docs for the different versions of TG.
This setup should really make porting from Moin to Docudo
straightforward.
So, Docudo.org will continue to be the best testbed for Docudo.
Kevin
Jorge Vargas
http://www.voidspace.org.uk/python/rest2web/
it's from the guy that created ConfigObj so I can trust it :)
Lee McFadden
>
> I really appreciate all of the offers of assistance, and I think I've
> worked out the details (haven't implemented them yet) of a good stop
> gap approach. I'll set up a wiki with Moin Moin and a certain set of
> plugins which will give us many of the benefits of Docudo (the big
> thing that will be missing is the workflows we have in mind) and some
> of the other cool things we would likely come up with given the focus
> of the project.
How is this transition going? Is there anything I can do to help
speed up the process? Since starting a few contracts that are using
TG as the framework I've been combing through various docs and piecing
together snippets here and there. I've built up a little doc
repository of my own :)
As it is, I don't want to touch the "official" docs as I feel it would
be wasted time but there's nowhere to put the stuff that I'm writing
up at the moment. Any assistance I can give in creating the central
docs repository will help everyone, including myself. :)
Lee
--
Lee McFadden
blog: http://www.splee.co.uk
work: http://fireflisystems.com
Kevin Horn
Kevin Dangoor
> speed up the process? Since starting a few contracts that are using
> TG as the framework I've been combing through various docs and piecing
> together snippets here and there. I've built up a little doc
> repository of my own :)
It's coming along well. I've been experimenting with MoinMoin to make
sure it (and the various plugins) are really doing what I want. (They
are.) I'm about to the point now where I can work on converting our
existing documentation over. Once I've done that, docs.turbogears.org
will be open for business... we'll need to start converting things
over from the existing Trac wiki and also grabbing anything we want to
keep from our brief time using Docudo.
As with Docudo, "official" docs allow comments but no edits (unless
you're an editor). There will be a new doc playground area where
people can contribute random docs that can later be made official...
> As it is, I don't want to touch the "official" docs as I feel it would
> be wasted time but there's nowhere to put the stuff that I'm writing
> up at the moment. Any assistance I can give in creating the central
> docs repository will help everyone, including myself. :)
I'll put docs.turbogears.org back online with Moin as soon as possible.
Kevin
Kevin Dangoor
>
> I think the Trac wiki would be the best place for random notes and stuff.
As soon as a couple people other than me have poked and prodded at the
Moin setup, I'm going to turn off write access to the Trac wiki.
About the only unfortunate thing that I've seen with Moin so far is
that I can't *force* people to use ReST. I don't want to have to do
lots of wiki markup<->ReST conversion all the time...
Kevin