Specification Documentation that you can really reference

Question

Hi,

At the moment I am using Visual Source Safe (yeah yeah!) to store my Technical Specification documentation.

The actual docs are written in MS word.

If find that having the spec written in word format to be a big burden, for specs to be truly used there shouldn't be any barrier to usage and more importantly access.

If I can't quickly scan a document, hyperlink to other dependant documents or sections, what use is all this anyway?

So with that as a background:

what software exists to create truly accessable documentation? i.e. hyperlinks to other pages/sections etc? Or even queryable so I can view all documents that are dependant on module 4.5.3

Is it basically just a Wiki? Anything else?

Answer 1

I believe Word supports the idea of sub-documents (links to other documents), however I'm not sure how well it works without VSS, much less with VSS. But it's something to look into.

A wiki is, however, pretty much what you are looking for.

Answer 2

Wikis are great for creating and maintaining specs. However, it is difficult to generate a big ol' paper document that makes a satisfying "thud" when you drop it on peoples' desks.

I've gotten by with Word. Just learn to take advantage of all the automation it has for cross-referencing, indexes, tables, pagination, etc.

I think of specs as having two audiences: decision-makers and developers. The Word documents are for the decision makers. The developers will come up with something useful later when it is time to implement the specs.

Answer 3

Java has API docs generated by javadoc, Python has API docs generated by tools like epydoc.

What language are you working in? Have you looked for tools like javadoc or epydoc for your language?

Answer 4

We just started using Confluence for technical docs and notes: http://www.atlassian.com/software/confluence/

It's a full-featured browser-based wiki that just works out-of-the-box, though you can tweak it to your heart's content. It features everything you'd expect from a professional wiki, including security, rich text, hyperlinks, and attachemts; and it's intuitive enough that even our non-technical people (with 3-letter titles starting with 'C') use it.

If you visit Atlassian's web site (see link above), you can play with their online demo ... and they eat their own dogfood to provide community support.