As you might have gathered from my last post, over recent years I’ve found a team wiki to be almost indispensable. I think every software development team should have one!
So what is good to put up on a software development wiki? Overall I think the goal of a team wiki should simply be capture anything useful that the team knows, as far as it is possible and reasonable. At the very least it should hold details of how to get stuff done, in order to maximise productivity of the team while minimising errors due to inaccurate information
Generally, I have found that “How-To’s” work well, as do checklists, explanations, and any sort of reference information.
In more detail, here is a list of things that I have found useful to have on a software development team wiki:
- Diagrams and explanations of system architecture
- Design considerations/limitations of certain aspects of the system
- Data flow within the system and to/from other systems
- Application-specific business (domain) knowledge
- Coding How-To’s for developers, such as how to add new components to the system
- How to set up environments. For example, how to set up a new development environment, how to set up a new QA box, build machine, etc)
- How the build process works and how to perform different builds
- Pre-release testing procedure, including sanity checks and regression testing
- Release procedure (including pre- and post-release tasks)
- How to perform deployments
- Details of user acceptance testing
- Details of who to contact to get stuff done. eg, “to create a new user account, contact X team at Y email address”
- Checklist of items to be done before new employees arrive
- Details on how to make requests, eg how to request a new machine, how to request different accounts to be created
- Email templates. eg, for requests, or for standard emails to users
- How to solve typical support issues, possibly with links to issues in a support system (eg, jira)
- If working in iterations: how to create a new iteration
- If working in an Agile environment: information on past spikes that have been executed and results achieved
- Project planning information, like goals, milestones
- Ideas for new features
- Ideas on how to improve technical aspects of the system and/or development process
- Details on servers that the team “owns”/accesses
- Information on server-side services that regularly run in the background
- Details of down-stream systems that consume output from the system
- Coding standards
The target audience of such a team wiki can be broad: developers, QA, support, managers, members of other teams. I have also found it very useful put information for users up on a wiki when working on company internal applications. Users then see the latest information, and can even update it themselves if necessary!
Taking this idea further, why not use the wiki as the source for application help? Help pages are so 1990’s, aren’t they? With a wiki, any questions or issues that users have can then be documented (and improved) immediately, rather than waiting for the next release.
The goal of including information for users on a wiki is to keep users better informed and reduce load on the team in supplying information to users, thereby improving the team’s productivity.
Some specific items I have found useful to put on the wiki for users:
- In general, anything that can help users use the application more effectively
- How To’s, with screen-shots and walk-throughs
- Results and procedure for user acceptance testing
- Manager/developer contact details
- Release notes
- Meeting minutes
- Discussions of requirements
How about you, have you found any of the above useful to put on a wiki? Please feel free to add your suggestions.
Great points mate!