Project documentation (initiation, requirements, etc) on a WIKI versus requirements word document?

Question

A team was having a debate where historically we had project documentation (requirements analysis, technical specs) put together large Microsoft word documents. Looking back over time, I have found issues with this approach, including:

• Lack of links back to current or related information
• Hard to search
• Hard to collaborate on
• Intimidating (even with "sections" and table of contents, still seems worse then being able to breakup Breakup into several linked pages)

One school of thought is to switch everyone over to just using WIKI for all documentation. Unable to get any objections that seemed valid after discussion so just wanted to shoot a question out to this audience and see if there is any valid reason someone can think of to using separate word documents.

NOTE that the WIKI could always export as MS Word or PDF as required.

Answer 1

In either case the big issue is with the data contained becoming stale. A wiki will have more robust version control information. We collaborate using markdown and gists on github to build out documentation of component parts where members are responsible for portions then the whole document is compiled and reviewed for completeness.

In terms of using static doc files, this seems very debilitating for larger projects, and cumbersome for small ones. Google Docs has a more robust collaboration and version control system though if you wanted to go in that direction.

Answer 2

Having everything public on a Wiki may make people more likely to refer to it. In my opinion documentation I can't easily access isn't good documentation. I've advocated for and used Wikis on a couple of projects. There are systems, such as Trac, that combine a Wiki with a bug tracking system and links to the version control system.

I've worked on a project where all official documentation was under "Version Control". The only problem was there was no known mechanism for the project team to get documentation out. Developers and analysts alike worked from drafts. Documentation revisions were done from drafts which were maintained outside the "Version Control" system.

There will likely be information such as financials that you don't want on the Wiki. You will need appropriate mechanisms to ensure they are available to those that need them.

Answer 3

The best reason for not using a Wiki is if you have key stakeholders who are uncomfortable or unfamiliar with them. If this is the case you may be able to go with a hybrid approach, i.e. msot of your documentation is on the Wiki while particular key documents (e.g. your baselined schedule) are static.

For example, maybe you have a project business sponsor/champion who understands the business needs deeply but doesn't have the time/knowledge base to run through a series of documents on your Wiki to figure out how you got from A to B. In this case it might be much better to provide point-in-time summaries of decisions, changes etc as static documents.

Answer 4

If everyone who needs to read or modify your documentation will have direct access to the wiki (and are comfortable using it), it sounds like you've considered what you need. However, it gets more interesting if not all parties have access to the Wiki (for example: your wiki is on your company's private internal network, and there is a need for external people need to either read or modify your documentation).

If you have documentation that needs to be read by external people, consider how often you're going to need to provide a copy to them. While you say you can export the wiki to Word or PDF, you'll almost certainly need to do some cleanup of what that export process generates before handing it off to those people. If you've got documentation that you need to update and send out frequently, this could become a pain point. Consider keeping those kinds of documents in their current form rather than moving them to the Wiki. It is possible that depending on the wiki you could make use of some templating to simplify this process (but that depends a lot on what wiki you are using). While templating may not completely eliminate the pain, it should reduce it.

If you have documentation that needs to be modified by external people, you should almost certainly leave those in their current document formats. If you did move them to the wiki, you would not only have to deal with cleaning up the export results before sending to the outside editors, but you also have to handle getting their modifications back into the Wiki (requiring additional time, and possibly introducing errors).

Answer 5

In your question you put "a bunch of word documents" on the one side and "a wiki" on the other side.

Reality is that Requirement Management Systems out there (take the top N) are there because there are hundreds, if not so thousands of requirements FOR such a requirements management system.

• A requirements solution OF COURSE should include support for different input formats like word documents or scanned white boards
• centralized access for everyone within the company and trusted outsiders
• the capability to produce traceability matrixes for impact analyses
• the capability to version and baseline certain requirements (e.g. release 2.3.1. run currently on test server A, release 2.3.4 on test server B and release 2.3.5 is currently used for training end users) (or... the set "funtionality C" will move to the next release)
• the capability to extract singular requirements from documents and store them as records / wiki entries with unique numbers, attributes (import/not important), tracebility to what RFC's, Defects were found this this.
• To support different quality and security processes which all have their hunderds of checkboxes on what the requirement solution MUST be able to do.
• To have adequate security roles support / auditing options "send me e-mail when someone touches my requirement)
• To store each RFC/Defect/Etc... with each singular requirement
• etc... etc... (etc...)

There is a certain baseline "core" set of requirements for RM system that everyone can write down in a certain amount of minutes. E.g. the set above.

But then there are the additional requirements often coming from the specific roles in an organization AND the processes that a company has standardized out (which encompass e.g. governance regulations and different quality frameworks)

So your requirements management solution contains hundreds of puzzle pieces underneath, one of the puzzle pieces could be a wiki.

you write "A team was discussing..."

In my experience the requirements FOR a RM system are often stated in the context of the role a person has in an organization and often these requirements conflict. Development Teams have total different look on requirements as e.g. operational architects or business analysts or support technicians or maintenance and theirs needs differ on what they are looking for.

An architect for instance wants to have integration with his Architect system so that he can (sandwich approach) start architecting the solutions with layers of requirements , models, requirements, models, all integrated with the solution.

So you should regard the requirements phase and selection for a RM system the same as for any other system: write down all requirements for you RM system from all partys involved and you find an enormous amount of requirements for a RM system, often not understood by other participants. Workshops etc... could help out there as well as demo's from the TOP N Gartner quadrant RM systems.

But... if you succeed in making the complete list of requirements for a RM system it becomes much clearer for all participants if a requirements wiki alone is a solution (based on the products on there)

you Write "Looking back over time, I have found issues with this approach"

On your experience with using Word Documents: it seems that you have used the Word Documents themselves to collaborate on and work on requirements. Word documents are not requirements. They are Requirement Documents. Each of them contains the atomic requirements so (also classic) RM systems extract those atomic requirements out of the word documents and store them as individual atomic REQUIREMENTS where you should collaborate on, version, etc... It would indeed be crazy to treat word documents as the requirements but as far as I have seen no project has ever treated requirements as `a directory of requirement documents´. Ofcourse these are not THE requirements, you should always extract the individual requirements (and give them a type like use case, non functional, functional, process, release or whatever) (and have a diagram that explains the relations between the types). Furthermore ofcouse an update to an individual requirement item in your database auto updates the word document (like many RM solutions do).

Integrated approach

I think we left the stage of different tools that together form the integrated solution to support your process (requirements management, configuration management, change management, defects, etc). I think we are at the stage that most companies are looking for yet the next step: A platform to plugin all of the different puzzle pieces that seamlessly guide any role throughout a process (standardized, adjusted and auto support for all major process frameworks e.g. ITIL for maintenance, agile approaches from dev, Prince 2 for PM, whatever is standardized on, etc....) without the need for them to switch to different tools for different tasks.

wiki thinking (core)

a Requirement is anything you can trace to something else. E.g. A [house] has multiple [window]s. 90% of the people thinking on requirements treat requirements as the dictionary 'common folk' explanation of a requirement. Therefore e.g. treating 'release 1.2' as a requirement is often not understood (because the base understanding misses).

So what your actually doing is building a taxonomy.

From that thinking hypertext stems: the reason that the World Wide Web works like it does is that it can link items together. (and Wiki gives the awaited option for everyone to edit pages)

So both systems (and probably a lot of other systems) use the same approach of how people can structure information:

If we have a gazillion insects we need to put them in a taxonomy. If we have a gazillion requirements we need to put them in a taxonomy. (just to understand complexity).

Furthermore both are going through change and support changes. Both also support linking to individual items.

So it is logical that wiki comes along especially since about everyone can use a browser and knows the internet.

A wiki THEN needs to support the additional requirements as a RM system and there the problem starts: on wiki e.g. plugins need to be written for integration, to support baselining, etc... etc.. etc.. You could say that so much has to be written on top of the wiki that the wiki part in terms of pieces of code for the solution only forms a little part of that solution. On that moment the thoughts rise to make the step to a RM system that is often build from a more holistic approach. But that moment only comes when the requirements for that RM system become more and more and more.

Answer 6

Might be the single most important issue for project documentation: It shall be very easy to identify reasonable information for somebody looking it up

Answer 7

A wiki is an aspiration, not a solution. You are suggesting that if everyone (or several) people involved in the project were empowered to keep documentation current - and encouraged to do so (e.g., part of their job description) that documentation would remain fresh. That is true regardless of what you call your repository - Sharepoint, wiki, whatever. In fact, if Sharepoint doesn't have wiki tools built in, MS Teams certainly does. But that doesn't change the main issue

The reason I say, "aspiration", not a solution, is that the culture has to be such that (a) links, documents are kept current, but also that there is active "gardening"--someone archives what needs to be archived and ensures that subject matter experts (SMEs) keep that documentation current. In most places, that does not happen, so what a change to "wiki" vs Sharepoint actually means is that the name of the tool changed without a change in culture. The change in culture is the critical piece. The tool is incidental.