Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Are there any resources available around that suggest 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.

Thanks!

share|improve this question
    
Thanks for all the great comments so far. –  kerrin Sep 10 '12 at 7:54
    
I'm thinking of having a basic home page for each dev project or unit of work that includes headings like functional description, key contacts, approvals, source code listing, who's testing and with what data, etc. Does anyone have something like this that they are happy to share? Something that would form an online cover sheet for each development activity. Thanks again –  kerrin Sep 10 '12 at 8:01
add comment

3 Answers

up vote 8 down vote accepted

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.

fundamentals

value feedback

Ask for, collect and record any feedback you can get - mail, wiki page comments (most convenient btw), messenger, conversation.

  • recording feedback

    • Q: what if I currently don't have time to properly process the information?
    • A: save it at the page as-is - for future processing and hide it from regular readers like as follows: {excerpt:hidden=true}information to be processed later{excerpt}
  • processing feedback

    • try to do it as fast as possible. Details and context that look obvious to you or submitter right now, can be forgotten a day or week or month later  
    • consider alternative solutions to problem(s) pointed in feedback. Example:
      • (feedback) hey the information I need is mixed with useless one
      • (wrong action) OK I remove stuff you don't need
      • (right action) OK I will split the information to one of your interest and the rest that might be of interest for someone else

handling suggestions implying long term work

  • Q: what if suggestion is like say "collect and rearrange all relevant data documented at thousand other pages"?
  • A: add a TODO-s section to your page (if it's not there yet) and record the suggestion in this section. Later, you can use it also to track your progress
    update DD.MM.YYYY: 475 pages of 1000 are processed

handling suggestions that look wrong to you

Side note it never hurts to ask the suggestion submitter for clarification. Though, you'd better do your part of job first:

  • check the page history, taking into account review date. There is always a chance that submitter points to the issue from older version that is already corrected
  • look closer at the page/section referred to and ask yourself, what could cause him/her to think that way?
  • (after a little training with trick like above) you'll find out that in most if not all cases, there is a distinct area for improvement there.
    • Imagine for example, user complaining about missing information which is actually present somewhere in the page. Despite looking wrong on the surface, such a complaint often indicates a serious problem at the page: namely that some important information is hard to find. Giving it a visibility it deserves will improve the page.

better fast than perfect

Rely on review and feedback. If something really needs correction, time will sort it out for you

  • this also applies to self-review. Record the draft of what you want to put to page and review it yourself an hour (or day, or week) later - this trick can do wonders
  • don't waste time on making things perfect at the first try - it's impossible
    • record the information as soon as it looks barely acceptable and ask those interested to review it

be bold

Be bold when updating pages: fix problems, correct grammar, add facts, make sure wording is accurate, etc.

  • Above is based in Wikipedia principle and is best explained, well, at Wikipedia
    • ...but please be careful - take care of the common good and not edit recklessly: a clarification to principle above,
      also explained at Wikipedia

advanced

be thankful

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.

explain TLA-s

If you can't figure what's TLA? - you've got the point

  • use links for that if possible: TLA

record answers to questions

Respect others time - record answers

  • It might take you one second to answer to question, but think about the guy who asked it instead? (S)he took time to read your page, to try to find the answer, to contact you and wait for your answer. If you record the answer at the page, you'll save all that time for next guy having this question.
  • Record answers to your own questions. What is unclear to you, might be unclear to the next reader.

use question marks

When in doubt, use question marks

  • Confluence syntax as an example: (?) Example: (?)<this info> needs checking(?)
  • this way, any reader can clearly see what sort of info you need; chances are high that someone can help you clarify things

links are your friends

  • DRY - don't try to copy information when you can provide the link instead
  • learn to summarize when needed
    • some link - hey what's this?
    • some link - Wikipedia, the free encyclopedia that anyone can edit.

visuals matter

  • When you have time, self-review your page asking yourself if it is easy for the reader to get the point(s) you are willing to make
  • It can be quite difficult to find substance in an unstructured stream of consciousness

    ...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.

relax and have fun

Keep in mind that typically readers of your page are not required to be dead serious.

  • when you feel it's appropriate to have fun - have it

http://i.stack.imgur.com/CH9n7.gif

fight link rot

  • You are willing to move some page or resource?
    Fine, just think about the guys keeping links to it somewhere in their bookmarks, emails archives, documents etc etc
  • When you (re)move the page or a document, keep a placeholder where it previously was located, to help visitors understand what happened to it and where to go instead
    • <this page> has been moved to <that page>
    • <this document> has been removed because of <the reason>

References for further reading

share|improve this answer
    
Thanks gnat - some really goods points there –  kerrin Sep 10 '12 at 7:49
add comment

First, it is important to choose a good Wiki. Choose one that:

  1. Is well maintained and has good support.
  2. Supports user authentication and has access control on documents or namespaces.
  3. Tracks changes to documents and provides a history.
  4. Allows E-mail notification of document changes.
  5. Has a good editor, preferably WYSIWYG, and supports lists, tables and uploading images.

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.

share|improve this answer
    
Do you have a recommendation for a wiki that matches those requirements / what do you use? –  Daniel B Sep 7 '12 at 13:05
    
Try Confluence (atlassian.com/software/confluence/overview) or SocialText (socialtext.com). –  akton Sep 7 '12 at 13:17
    
thanks for the update. –  Daniel B Sep 7 '12 at 13:35
    
Yes, we use Confluence (throughout IT) and highly recommend it - it's just the apps team that have resisted to date :) –  kerrin Sep 10 '12 at 7:51
add comment

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.

share|improve this answer
    
Totally agree drekka - I want to find a mid-point between being too prescriptive with strict structure and page templates and not having developers intimated by the blank page. At least in the first instance. –  kerrin Sep 10 '12 at 7:53
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.