11

the goal is to have an online documentation system, with these major requirements:

  • will be mainly used as an intermediate stage for the final technical docs of all our application (which will probably never get completed though :]). It would be typically used as so: someone has a problem, I fix it, and write down the fix immedeately. What happens now is getting unmanagable: someone has a problem, I fix it, both me and someone are happy but 2 months later somebody else has the same problem and nobody remembers what the fix was.
  • accessible from everywhere, running behind our apache server
  • user/group managment, allowing read-only/read-write/admin access
  • the format is not too important: plain text would do, wiki-style would be nicer though
  • cheap or free

some ideas of mine:

  • just serve files on a file share or through ssh (cons: not too copmatible with windows, pros: simple, can be any file type)
  • keep it in an SCM (svn/git, idem as above but easier to access and control access)
  • Confluence: we use Jira already, is Confluence worth it? How does it integrate with Jira?
  • something else?

Please don't hesitate commenting on these or share your experience with other systems.

stijn
  • 4,138
  • Is the documentation being generated from code (such as Javadocs) or is it being written from scratch, as a user guide, or some combination of the two? – FrustratedWithFormsDesigner Jan 20 '11 at 14:47
  • it's mainly more of a user guide, not code documentation (well, we have that as well, generated by doxygen, we might include it, but it's not the first point of interest) – stijn Jan 20 '11 at 16:04
  • I would hand over some cash to Spolsky. – Job Jan 20 '11 at 16:13

1 Answers1

11

I was going to suggest a Wiki

As Confluence is a wiki I think using it with your JIRA is an excellent idea. You'll have the advantage of being able to directly tie back into JIRA issues, and therefore the actual code/doc/whatever change made etc.

The key to any code doc repo like this is the navigation aspect. You don't want pages that are disconnected, hard to find etc. Do put in thought to a 'site layout' much like you would for a web site.

Martijn Verburg
  • 21,986
  • Confluence can apparently export in various flat formats. Sounds like one of the easiest ways to get from easily-editable to finished produc.t –  Jan 20 '11 at 11:31
  • 2
    We have Confluence where I work—we migrated from MediaWiki—and it does a good job outputting to a number of formats (Word being the most popular). But be warned its WYSIWYG editing tools are incredibly buggy and the tagging system leaves a lot to be desired, at least on our install. – Philip Regan Jan 20 '11 at 11:37
  • +1 for Wiki, I also found Trac very useful in that case as it integrates with SVN allowing file sharing as well. –  Jan 20 '11 at 11:46
  • we checked a Confluence trial, and it's going to be the solution. Seems to be able to do way more than we need, but it's pretty easy to work with. I tried Trac a couple of years ago and it was a bit too messy to my taste, especially when it came to plugins etc. – stijn Jan 21 '11 at 07:41