That Wiki Thing...

It's been roughly a year since my pet wiki has been active on the company's intranet. It's definitely been useful, but I think it hasn't completely lived up to the hopes and dreams I had for it.

Usefulness to My Good Self

As I'd planned, I've been using it as a kinda design notebook, although I still scribble on real paper as it's the quickest way to record thoughts. When I write a wiki page, I find I write for an audience other than myself. And that's no bad thing as I have to state assumptions and 'formally' defend any assertions. I'm convinced this is ok; my paper notebook is for exploration and the wiki is the crystalisation of the thought process that lead to the final design. The wiki is the definitive source of information about a topic, not a discussion. The wiki has added a sense of rigor to thinking behind the stuff I produce.

Y'know, maybe I shouldn't be setting up wiki pages willy-nilly. I shouldn't actually be doing my design in wiki pages. Wiki pages are supposed to be solid information, not cloudy half-thought-out explorations. It should not really be an extension of my paper notebook, should it?

Usefulness to My Teammates

This is harder to judge. I think it's somewhat useful to my teammates in a read-only sense, but that it's still considered as "Marty's wiki" and not "the wiki" as I'd hoped.
I have made an effort to let people know of its existence. After I complete a body of work, I check that the page in the wiki is reasonably accurate and then the link is sent around in the 'announcement' email. For example:

Hi All, I'm finished setting up the co-sim environment for our latest chip (which is the bee's knees, BTW, and going to make our company millions). See here (http://ourgroupswiki.some.address.com/) for info on the environment and instructions for launching a sim

That sort of thing. And there is evidence that people read it, but they don't edit it if something's amiss. I do get the odd query on the accuracy of instructions, but my teammates never change the information themselves. Maybe they've better things to be doing - maybe they don't feel that they're an expert in that field so need consensus. Who knows?

The Elephant in the Room - Sharepoint

The wiki's relationship with Sharepoint is still mostly undefined.

Sharepoint is our company's blessed online collaboration thingy. But it's become a dumping ground for powerpoints and word documents. And mostly Office 2007 versions of stuff I've no hope of opening on my linux workstation (vendor lock-in, much?). Rant aside, this is where the latest datasheets, latest marketing info, latest formal design documents go. And to be honest, it's probably the correct place for that info.

So...

I need to properly define the wiki's place in the grand scheme of things. I know it has one, but I haven't yet been able to articulate it. I also need to ask my teammates why it's not "the wiki" yet.

I dunno why I'm invested in this so much.

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"