Johnson, Eric wrote:
Dan,
That is close to what I was originally proposing to do.
While I don't understand why writing a long piece of documentation on a
wiki is any easier than writing it using a WSYWIG editor that supports
HTML or DocBook
1. Often you need to work at the source level of HTML/DocBook
2. There is an additional generate, commit & publish cycle when docs go
live.
3. There is no snippet macro, which means no unit testing of examples
To expand on #2: I've done static sites at Apache and they're a pain. A
typical cycle:
1. Write docs.
2. Generate on your local machine/
3. Check that things are formatted correctly.
4. Commit to SVN.
5. Log on to Minotaur and issue an SVN update
6. Check that everything deployed correctly.
Go back and repeat. You can see how fixing a link becomes a 10 minute
process. This is a deterrent to improving docs. I improve the XFire
docs probably once a day. Can you imagine how much time this would take
out of life if I did that?
I accept that asking developers who are busy writing
code to learn a new tool is a hassle.
Its not about learning a tool, I'm happy to learn a DocBook or whatever,
I just want to find the best tool for the job.
It is possible to allow user
facing docs to go up on the wiki as drafts and then, once they have been
reviewed and polished up, be moved into a static area and a format that
is consumable by outside projects - such as IONA.
That might be an option.
I am more than happy to do the grunt work of keeping a non-wiki home
page and static user docs up to date. That is what I do for a living and
since my Java skills are less than enterprise grade, I cannot really
help out with submitting code...
I appreciate you volunteering, but I don't think you're going to be
doing all the doc writing. While IONA is a large part of the project
others will be writing about features which they themselves implemented,
that IONA probably won't have any interest in. So I think we need to
pick our documentation tools with the realization that we're trying to
get many people involved. A good example of this is an XFire migration
guide? XFire developers will probably need to write that as we're the
only people qualified people.
I'm not trying to rag on any of your suggestions here or say we can't go
down the static route, I just want to evaluate what the best option is.
So I guess I'd like to know: what tools are you thinking about using and
for what type of content?
- Dan
--
Dan Diephouse
Envoi Solutions
http://envoisolutions.com
http://netzooid.com/blog
