Wikis

Keeping Engineering Info in Wikis

I'm starting an experiment at work. I want to liberate the design notebook. And this revolution will be wikified.

If my group 'published' sections of their notebooks on an intranet wiki, I'm convinced we'd see lots of benefits. I realise that having a paper trail is very important for patents and such, but I don't envisage the wiki replacing the notebooks - rather that the entries in the wiki would be a somewhat more polished version of the more interesting and useful scribbles.

What goes in the wiki?

Lots of things. Solutions to weird bugs. Testbench documentation. I'd even suggest that an entry for every major new block in each project goes into the wiki, with the important legacy stuff added as we go along. The block info would detail how the block works and more interestingly, why the block is. More info than in an email introducing the block, but maybe less info than for a design review. Even technical questions in emails to you could serve as topic pointers for a wiki page.

I think it's the wrong place for sim results. It's wrong for block pin lists or schematics. It's probably the wrong place for anything which has to be copied from other sources to keep it up to date.

Benefits of Wikization

The obvious benefit is that all this stuff which normally lives in only one or two people's heads or inboxes is available to and searchable by the entire group. Another benefit is that writing an entry in the wiki should focus the designer, making them think more about what they're doing which should help increase the quality of our designs. It would also be a ready-made source for info and text for design review documents, datasheets, customer presentations and the like.

Resistance

There are a few drawbacks, though. The main one is getting buy-in form the rest of the team. I'm not naive - I know that if I tried to get it decreed that everyone has to use the wiki in the way I outline, it would raise eyebrows, roll eyes and be dismissed as another layer of red tape and beaureaucy.

I have a plan* though - I'm going to lead by example and people will see the revolution as righteous. I've started to put interesting stuff in the wiki and I'm starting to point team members to it when they come looking for info. They're eventually going to start thinking, "Hmm, Marty would know that, I check that wiki thing of his before I ask him". This is going to be cool for a while until they spot an error, at which time I'm going to lightly suggest that they get themselves an account and fix it up. They're going to see the benefits of the wiki and start adding information themselves and things will get cooler. OK, there was a leap of faith there, but there's no harm in trying it out.

Aside: We've also a Sharepoint site too, but this seems to be a place for dumping documents and todo lists. I'm going to have to think a bit more about how the wiki fits with it.

Initial Wiki Usage Observations

So. The wiki I'm using at the moment is Wikimedia, because that's what sysadmin kindly set up for me. I like the way it stores edit history. I am finding it useful.

The main problem I see is with engineering diagrams. There's no stable drawing plugin for that species of wiki. State diagrams and example timing diagrams have to be created elsewhere and uploaded as .pngs or whatever to the wiki. I don't like the fact that the master document for the diagrams is elsewhere, making it difficult for others to correct or append them. And even if there were a stable drawing plugin, would the drawings be of high enough quality to use in more formal documents?

I think diagrams are important in engineering documentation, and would love if the barrier for entering diagrams into the wiki was lowered. I'd love if we all had graphics tablets (or tablet PCs) and could just scribble a quick diagram only for it to appear in the wiki. I'm contradicting myself here a little, but if it's a tossup between no diagrams because its a pain in the arse to get them in the wiki and sketchy diagrams that need to be redrawn with more care for more formal documents, then sketchy wins for me all the time. I like diagrams...

Future

I think the future of our group has a wiki in it. Lets see how the experiment goes...

Resources

• twiki


• wikimedia

* OK, it's not really my plan, I robbed it from http://www.randsinrepose.com/ , or more specifically, his book "Managing Humans"