Software Engineering Stack Exchange is a question and answer site for professionals, academics, and students working within the systems development life cycle. It only takes a minute to sign up.
Sign up to join this community
Looking for best-practice structure for setting up a wiki for developers?
I'll be managing a team that has not had the best track record for documentation, communication and knowledge-sharing. I'd like to have a framework set up to make it easier for the team to get started in this area.
Don't focus too much on getting a perfect structure up front, better let it grow organically. It's the communication culture and process that matter.
Below are some tips to maintain team wiki.
Ask for, collect and record any feedback you can get - mail, wiki page comments (most convenient btw), messenger, conversation.
recording feedback
{excerpt:hidden=true}information to be processed later{excerpt}processing feedback
update DD.MM.YYYY: 475 pages of 1000 are processedSide note it never hurts to ask the suggestion submitter for clarification. Though, you'd better do your part of job first:
Rely on review and feedback. If something really needs correction, time will sort it out for you
Be bold when updating pages: fix problems, correct grammar, add facts, make sure wording is accurate, etc.
People giving feedback are a valuable asset, be thankful to them. These people took their time and effort to not only read your page, but also to provide their feedback. Vast majority of your users won't be that generous to you. Those sharing their thoughts are "the cream" of your audience, be thankful for their contribution.
If you can't figure what's TLA? - you've got the point
Respect others time - record answers
When in doubt, use question marks
(?)
Example: 
<this info> needs checking...I gave him all the pleasure I could leading him on till he asked me to say yes and I wouldnt answer first only looked out over the sea and the sky I was thinking of so many things he didnt know of Mulvey and Mr Stanhope and Hester and father and old captain Groves and the sailors playing all birds fly and I say stoop and washing up dishes they called it on the pier and the sentry in front of the governors house with the thing round his white helmet poor devil half roasted and the Spanish girls laughing in their shawls and their tall combs and the auctions in the morning the Greeks and the jews and the Arabs and the devil knows who else from all the ends of Europe and Duke street and the fowl market all clucking outside Larby Sharons and the poor donkeys slipping half asleep and the vague fellows in the cloaks asleep in the shade on the steps and the big wheels of the carts of the bulls and the old castle thousands of years old yes and those handsome Moors all in white and turbans like kings asking you to sit down in their little bit of a shop and Ronda with the old windows of the posadas 2 glancing eyes a lattice hid for her lover to kiss the iron and the wineshops half open at night and the castanets and the night we missed the boat at Algeciras the watchman going about serene with his lamp and O that awful deepdown torrent O and the sea the sea crimson sometimes like fire and the glorious sunsets and the figtrees in the Alameda gardens yes and all the queer little streets and the pink and blue and yellow houses and the rosegardens and the jessamine and geraniums and cactuses and Gibraltar as a girl where I was a Flower of the mountain yes when I put the rose in my hair like the Andalusian girls used or shall I wear a red yes and how he kissed me under the Moorish wall and I thought well as well him as another and then I asked him with my eyes to ask again yes and then he asked me would I yes to say yes my mountain flower and first I put my arms around him yes and drew him down to me so he could feel my breasts all perfume yes and his heart was going like mad and yes I said yes I will Yes.
Keep in mind that typically readers of your page are not required to be dead serious.
<this page> has been moved to <that page><this document> has been removed because of <the reason>First, it is important to choose a good Wiki. Choose one that:
The biggest thing an development team Wiki needs is a "gardener": someone who is responsible for determining the layout and structure of documents in the Wiki. It does not have to be a full time role but the gardener should have strong English and an aptitude for explaining things well. The gardener should create standard templates for pages, naming conventions and determine what namespaces are required.
The gardener is not responsible for creating the content, more enforcing its structure. For example, if someone makes a change to a product, the gardener is not responsible for making the change to the Wiki. However, the gardener is responsible for making sure the change gets made and that it is done according to the guidelines (not just tacked on to a separate, unlinked page, for example). The gardener may review the changes or delegate that to someone else.
It is important to structure the Wiki to meet the needs of the audience rather than the needs of those creating content. For example, if you have a dedicated UI or security or localization team for software development, do not put their information in separate sections. Put them in the same section that the developers are looking at. Having everything together makes it much easier to find, ensures things do not get missed and identifies out of date content faster.
A Wiki needs a change in mindset. Many companies are used to information being forced upon them. A Wiki allows the consumers of the information to modify it. This should be strongly encouraged (and rewarded if need be). If inaccuracy is a concern, have reviewers configure the Wiki to E-mail them when modifications are made.
An development Wiki needs a strategy to handle versioning. If you have a set of documents for version 1.0, what happens when version 2.0 is released? Some of the documents for version 1.0 may still apply to 2.0 but some may be superseded. What if a change is made to a 1.0 document after the release of 2.0?
A Wiki needs some way of measuring success. How many people are using it? Did they find what they were looking for? You do not necessarily need a large, unsightly rating and comment box at the bottom of the page but a simple "E-mail a Human about this page" link may be helpful.
Lastly, the usage patterns of a Wiki will change over time. Remember to review any standards periodically to ensure they are still meeting the Wiki's needs.
Whilst it's a nice idea that all project wiki pages follow a similar theme so that everyone knows where to find things, this won't really address the problem of developers not updating pages.
You need to find a way to get your developers to see enough benefit in doing these things that they drive it and want it done. Otherwise they will simply see it as another top down bureaucratic burden they could do without.
I've been in this situation, both where the wiki was a complete mess and where it was highly organised and formal. The wiki's state didn't effect the developers level of interested.
