Why creating a engineering wiki site. (Living Document) is a good thing.

Recently I’ve started at company that didn’t really have a good solid engineering wiki. Let me state the problems and if you fall in this category, you might want to start thinking about looking at your software development practices.

Problems:

• Knowledge Islands: Anytime and I mean anytime you need answers about something everybody always directs you to somebody else. The alternative is to spend so much time in code that might be so abstracted or not very transparent that although you CAN figure it out, the cost to the company is high. OR It’s pretty much impossible for said individual to move on to another project without constantly being bothered about his “design” six months after he’s left. When I say bothered I mean weekly.
• Knowledge Gaps: Do you have multiple efficient teams but all all of them don’t contribute to the over all “Engine” so that the car all moves in the same direction?
• Very unclear/no requirements: Agile does not mean you do NO documentation.
• Each standup/scrum master does their own thing: On this team you create tasks for unit tests and then you swap to another scrum master and unit tests are atomic and “should” be included in as apart of your tasks already.
• Engine that could: Do you have

Plenty more to add, but you get the idea I think.

Purpose of a Wiki

Some of the benefits of a wiki can be:

• QA can learn how functions changed or work from previous versions.
• PM's can disseminate information to peers, which allows feedback and question to better the existing design.
• PM's can build Releases Notes can be used to communicate outside of engineering about how features work.
• PM's can share with the entire company about their notes on competition, this helps share the knowledge of understanding to all in engineering to help employees understand the market we fight to dominate.
• Managers can use use simple and precise language and general propositions in new or existing processes, or evolve them to fit the reality situation.
• Managers can update status reports for their team, not handled in a TFS Query.
• Developers can reduces the knowledge islands which can can then allow people to move on to the new projects or not leave a knowledge gap.
• Developers to write a very high level outline functional and technical specifications (one page) of a Feature and can do so right after development has taken place. (Not before and not months after..)
• TAMS can build install guides which can be used inside/outside their existing team.
• New employees are empowered to find answers on their own, or become educated enough to ask solid questions.

..... Just to name a few advantages.

Q: Isn't having a wiki kinda anti-agile?

• Document writing is not anti-agile. Fostering open communication and getting feedback from others/customers is a important aspect of being agile. it's more efficient and it allows documentation to evolve from its original to a current working state as well as disseminate that information across the company.

Okay.. so I’ve convinced you to start a wiki for your engineering company. Here are some problems you will want to consider solving.

• If emails are sent out and they link a wiki page. What if that wiki page is changed. Portal sites like Sharepoint have static URLS so you if the page changes, the email link becomes invalid.
• Code Syntax Highlighting, it really helps.
• Flexibility
• Ease of Use
• Can it hook into your Active Directory?
• Does it have a good search?

My recommendation for all this: MediaWiki

Here are some tips for your wiki.

• Prefix all your pages with something like: We call it a “Manual of Style’
  • Design - 
    • (Code is the comment my butt), This page doesn’t capture the design the developer was “going” for. Or the “right” way they intended you to add to their design.
  • Tutorial -
    • How To, this lists step by step how to do something
  • Guide -
    • Best practices
  • Standard -
    • This is a YOU MUST follow this.
  • Process -
    • This is a stream line process. Not something to be blocked on. But it outlines easily what’s expected.  Do this, email this email group. here’s a template that details what we want to capture.
  • ….. etc etc
• Your SDLC (Software Development Lifecycle) should be focused on delivering business value with emphasis on high quality frequent releases. It should be based on the following four values:
  • Over communication
  • Empowering Teams
  • Continuous Iteration
  • Delivering Customer value early
• Build a Category system that fits your company. In my current company we have “many” products that “share” components. So I built categories that are “Features – “ Then everybody binds their page to those Features and all those Feature categories are bound to each Product that uses them. That way if they are shared they can be found easily. It also easily shows a Feature list for each product.
• Build a wiki syntax help page that details how to create a new page, or how to bind to the categories. etc.
• Build a email group of wikihelp and add in as many good solid stakeholders. So when question is asked, all get it and understand the solution. i.e. form a committee
• Organize your companies SDLC and Processes, show in there what’s expected from engineering (QA, Installers, Build, Devs, PMs, Mgr) on a Daily, Weekly, Sprint, Release. This way it’s clear and understood by all.

Adoption:

• Getting a company, it’s employees to switch gears and adopt this culture changing event is going to take time, you need to be active, leadership must adopt this and help enforce and promote it. Eventually it will take as time goes by and people will be able to see the benefits of being able to search for their own answers and understanding clearly what’s going on in the company and what’s expected of them.