Re: Tech Docs and Consultants

On Mon, 2003-04-14 at 13:03, Josh Berkus wrote:
> Greg,
>
> > Call me a traditionalist, but how about the traditional cvs + "your
> > favorite editor" approach? I don't think the techdocs section changes so
> > often that we need fancy wiki / edit-from-the-web-on-the-fly sort of
> > technology here. I also agree with Marc that there is no need to move it
> > elsewhere right now. Let's just keep it simple, focus on the content, and
> > add other things later.
>
> Simple: Because people aren't contributing content because it's too much
> work, both for the contributor and the TechDocs site administrator.
>

agreed

> 1) The majority of contributors to a Techdocs-style system will not have CVS
> accounts, do not need CVS accounts, and some of them find CVS baffling and
> confusing besides.
> If someone e-mails you an article and you tell them, "Oh, this is very good,
> why don't you sign up for a CVS account, just follow this 14-step guide and
> wait 8 days for authorization," do you think that that article will get
> posted?
>

agreed (meaning, no i don't think it will get published)

> 2) Raw HTML editing of a decent length article takes as long as writing the
> article itself, and I have yet to see a WYSWYG HTML editor which produced
> output that could be cleanly incorporated into a CSS site framework without
> extensive hand-tweaking.
> The result of this is one of 3 things:
> a) Some writers (like me) only contribute 1/2 as many articles because we
> spend too much time tweaking our HTML.
> b) Some writers contribute their articles to the admin as plain text, then
> forcing the admin to spend 10 hours per week formatting articles for posting.
> c) Some writers get discouraged by the long delay in posting, and give up on
> contributing.
>

yep

> 3) Except for the Guides pages, the tech for which is unfinished, the
> structure of Techdocs does not allow multi-user collaboration or comments.
>

whoa... what makes the techdocs guide tech unfinished? AFAIR Justin was
waiting on the switching of the techdocs site to a new VM, at which
point he was going to convert the whole site to the "guides" format. The
zwiki engine seems thorough enough for our use, and runs on postgresql,
so I don't see any reason to completely dump it.

Marc, are the VM issues taken care of?

> I *am* focusing on content, Greg. I want the focus of TechDocs to be
> content, and for the technology (including CVS and HTML markup) to be
> virtually invisible and take care of itself. The ONLY way to maximize
> contributions is to make them as easy as possible to make.
>

Absolutely. techdocs needs to be simple enough that people can "walk up"
and copy/paste their content and move on. Others reading that content
should be able to modify it if needed and move on. CVS doesn't handle
this well enough, zwiki does. I think bricolage does, though I'm not
solid on it's "anyone can modify anyones content" abilities.

> Lord-on-a-pogo-stick, no wonder MySQL AB is beating our pants off in
> community-building. MySQL.com doesn't require that a user have Stunnel, CVS,
> and intermediate HTML skills before they can contribute even a paragraph to
> the site!

Um.. what exactly is the process for contributing articles for their
site. Near as I can figure you send in an article and someone is *paid*
to convert it and put it on their site. I don't think we have the avenue
available to us.

More to the point they're are probably beating the pants off of us on
this issue because they have consistent, professional direction for
their entire web presence. Other projects have achieved this, but we
haven't.

> Justin has been trying to change this, and I want to finish that
> change.
>

Justin's change was to convert techdocs to zwiki after Marc resolved the
VM issues.

> BTW, all of the above really goes for the advocacy site as well, except the
> part about comments.
>

I think the target of advocacy is different, simply because you need a
more centralized message in place than what I think we're trying to
achieve with techdocs. Not that it doesn't need a lot of work...

Robert Treat