6

Our functional / business documentation is spread across Word files on our corporate Intranet. It's difficult to find and update information. There has to be a better way. Any ideas?

We had thought a Wiki would work great. Would seem to be an easy way to find information and easy for individual developers and analysts to add bits of documentation quickly and easily. We'd be curious to know if other development (or business analysis) teams use Wiki's with success.

The target for this documentation is the internal development team: developers, qa, and to a lesser extent business analysts.

Improve this question
4
  • 11
    I first read this as "fictional documentation", which seems somewhat more appropriate for lots of places I've worked at.
    – David Thornley
    Dec 19, 2011 at 16:24
  • @DavidThornley Haha!! :) ) +3 internets to you good sir!
    – maple_shaft ♦
    Dec 19, 2011 at 16:27
  • That kind of documentation usually requieres workflows and approbation levels/clearance for publishing, versioning, etc., which usually calls for a full-blown document management system.
    – Tulains Córdova
    Aug 4, 2016 at 19:34
  • You should check softwarerecs.stackexchange.com
    – Tulains Córdova
    Aug 4, 2016 at 19:44

8 Answers 8

Reset to default
4

There are various "single source" solutions for documentation out there. A number of teams I've worked with have had great success with Madcap Flare. I especially like how it integrates well with source control and provides support for creating context-sensitive help.

Full disclosure: I have NO relationship with Madcap, not even as a reseller. But I have never been so thoroughly pleased with a documentation product.

Improve this answer
3

At one company I have worked at we had a lot of success in using a Wiki as a repository for technical documentation. We tried getting the stone age business analysts to start using it for our benefit as well but alas, anything that would make them more accountable for out of date requirements documents or provide more transparency to their little fiefdom was met with brutal politically charged hostility.

Like all things though you get out of it what you put into it. Garbage in garbage out. There are also some helpful practices you can get in the habit of doing, like tagging pages with software release and build numbers so appropriate document history can be queried.

There is still the disconnect at that point where the version of the software is manually enforced to the documentation, in other words, the wiki is not being stored in source control. If you are diligent and maintain versioning of pages in your wiki then you will help mitigate this problem and still get the benefits of an easy to access and edit online repository of documents.

Improve this answer
3

We've been using the products from Atlassian. They have an integrated solution that combines JIRA, SubVersion, and Confluence (Wiki).

Improve this answer
3
  • 1
    +1 for the Atlassian products. They are the best as far as features, integration, and usability, however configuring and maintaining them can be an absolute nightmare.
    – maple_shaft ♦
    Dec 19, 2011 at 20:22
  • Thanks. We use Jira already so Atlassian is a good suggestion for us. Is Confluence considered a Wiki? I couldn't really tell from the website if it had all the features of a 'traditional' wiki.
    – Marcus Leon
    Dec 19, 2011 at 21:05
  • @BillIacocca - Confluence is definitely a Wiki, with the benefits that you get an integrated search with JIRA
    – Brian Hoover
    Dec 19, 2011 at 21:08
3

We've applied sharepoint for this, it has full text search for word doc's integrates nicely into Word and all the other Office apps. It provides version control and explorer integration so file management becomes pretty easy. It does however require a lot of upfront thinking/analysis on who-can-access-what to define search scopes, document access etc.

We tried a wiki but for non techies that somehow was too challenging (especially publishing images into wiki text). If you like you can mix the wiki with the document library, sharepoint has a basic wiki component as well.

Improve this answer
6
  • Did I read that right? You are claiming that Sharepoint is easier to use for non-techies than a wiki? Perhaps you were just using the wrong wiki. Atlassian Confluence IMHO is by far and away the easiest to use wiki product (from a user perspective) on the market right now.
    – maple_shaft ♦
    Dec 19, 2011 at 20:21
  • Our users just see Word as there UI so they realy didn't need to learn something new to start using sharepoint. That said, I did no perform extensive research on other wiki systems so you may be right.
    – Carlo Kuip
    Dec 19, 2011 at 20:24
  • I think our definition of non-technical user is a little different, but you must admit, writing a document on most wiki's requires less training and skill than learning how to use a proper word processor. Word is more complicated than a rich text editor on a web page in my opinion.
    – maple_shaft ♦
    Dec 19, 2011 at 20:29
  • Word is more complicated than a rich text editor on a web page in my opinion. I agree
    – Carlo Kuip
    Dec 19, 2011 at 20:35
  • "Our functional / business documentation is spread across Word files" means they have legacy documentation in Word. SharePoint is a great solution. Unless you think converting tons of Word docs is fun.
    – SnoopDougieDoug
    Dec 22, 2011 at 5:31
3

We introduced a Wiki some years ago into our company, for mainly the same purpose you described. Today, I have mixed feelings about the success. There are some very good articles, and some teams are using the Wiki well, but there is also a lot of garbage, someone started them once, with the notion of "I will complete the article later" but no one feels responsible for doing the necessary editorial work.

So when you are going to install a Wiki, don't underestimate the effort needed to fill the thing with useful content. Have some people responsible for the main structure and for cleaning up things. Make sure everyone knows what the Wiki should be used for (and for what it should not), and talk to your executives if they are willing to make it obligatory that certain parts of the business documentation must be "Wiki"-only.

Improve this answer
1

It's difficult to find and update information.

For whom?

Seriously.

There has to be a better way.

Actually, it may have a really good organization for particular users.

Other users may find it "difficult to find and update".

The most important thing to ask yourself is this:

Who is the audience?

If you have more than one audience, you may need documentation in more than one location. What you have may actually be optimal.

Once you know who the audience is, you need to clearly understand their use cases.

What do they want to know?

Until you have these two things clearly defined, there's no way to choose between your existing organization, a Wiki or -- perhaps -- less documentation with a better focus.

Since you didn't describe your audience or your use cases, we can't provide any advice at all.

Improve this answer
2
  • Audience is developers, business analysts, and QA.
    – Marcus Leon
    Dec 19, 2011 at 21:00
  • @BillIacocca: Please update the question to contain all the facts. Don't add facts in a comment.
    – S.Lott
    Dec 19, 2011 at 21:14
1

We are using Sharepoint to store documentation. We use the following directory structure for each project:

  • Requirements - Statements that identify attributes, capabilities, characteristics, or qualities of a system. This is the foundation for what shall be or has been implemented.
  • Architecture/Design - Overview of software. Includes relations to an environment and construction principles to be used in design of software components.
  • Technical - Documentation of code, algorithms, interfaces, and APIs.
  • End User - Manuals for the end-user, system administrators and support staff.
  • Marketing - How to market the product and analysis of the market demand.

Taken from http://en.wikipedia.org/wiki/Software_documentation

Improve this answer
0

We have been using Feature Driven Programming. We upload all the features which come out of the Functional Design meeting as excel to Clear Quest and then can be further linked to Clear case code or any artifacts.

So far in last 15 years of my career, Function Design and traceablity were never this easy. This model takes out of so much of time wastage which I have seen in other companies.

Basically our features live in ClearQuest which is easy to maintain , easy to query, easy to run reports on efforts, backlogs , easy for managers.

Feature Driven Development

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

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