14

I'm looking for software to organize and maintain projects internal documentation, specification, requirements, etc. Currently we store all documentation as lots of MS Word DOC files in a source control repository, which gives us version control, and that's nice. But you can't search this information, create links between them, categorize, collaborate.

Requirements, preferences:

  • Zero install on client side (WEB based).
  • Document version control.
  • Document annotations.
  • Document linking.
  • Full search (all documentation).
  • MS Word (*.doc) import\export.
  • WYSIWYG text editor.

Systems I have discovered and tried so far:

Alex Burtsev
  • 686
  • 1
  • 7
  • 15
  • What kind of project documnentation do you have (textual, graphical, UML diagrams, time schedules, textual specs, user stories etc.)? How many people have to maintain it? Must it be in sync with specific versions/revisions of your source code? – Doc Brown Dec 27 '11 at 21:00
  • @DocBrown, 95% textual, 3-5 people will write it. I'ts in sync with software products versions but not source code revisions. – Alex Burtsev Dec 27 '11 at 21:25
  • 1
    This is very close to being a duplicate of [What program do you use to write technical documentation?](http://programmers.stackexchange.com/q/79651/22493) and many of the answer are similar, but there are better arguments there against using a wiki for such documentation. – Mark Booth Jan 04 '12 at 17:28
  • Why not use google docs? – Ominus Jan 25 '12 at 01:18
  • XWiki looks like a nice solution it's free, it integrates with MS Office nicely. – Alex Burtsev Dec 28 '11 at 06:47
  • How about a knowledge management software like [PHPKB](http://www.knowledgebase-script.com)? It is not free but it seems to serve your purpose very well. – Anirudh Srivastava Jan 24 '12 at 16:57
  • Very interesting thank you, I quickly read features, and so fat it suits our needs. Funny thing, the page that describes import\export returns 404 :-) http://www.knowledgebase-script.com/features/data-import-export.php – Alex Burtsev Jan 25 '12 at 06:40

6 Answers6

6

How about something like Sphinx?

You write your documentation in reStructuredText (the syntax is similar to Markdown, which Stack Overflow uses) into plain text files (=easy to version control) and Sphinx spits out HTML pages.

The two most prominent Sphinx users (that I know of) are the Python language and TortoiseHG (see the links for the Sphinx generated documentation).

EDIT:

I just read that you are talking about project-internal documentation, not end-user documentation.
In my opinion, something like Sphinx is the best way for internal documentation as well (provided that you can get your analysts to write reStructuredText) because:

  1. You can easily version control the documents (and diffs of text files take much, much less space than binary files like .doc or .pdf).
  2. If a developer wants a nice readable .doc or .pdf file, he can create it with Sphinx from the sources.

If Sphinx is too complicated, there is even an easier way: you can write your documentation in Markdown and use Pandoc to create (for example) .rtf, .doc or .pdf files (it can do a lot more).
I found Pandoc easier to get started than Sphinx, but Pandoc can't create nice menu hierarchies like Sphinx (like in the Python and TortoiseHG documentation I linked above).

No matter which of the tools you use, if you have an internal web server and a build server, you can set it up so that the build server generates HTML output and copies this on the web server each time someone pushes something to the documentation. So your analysts don't even have to think about the final output, they just need to commit and push their changes.

Christian Specht
  • 1,863
  • 3
  • 15
  • 23
  • Looks like it just generates HTML then I will have to publish it on a web server – Alex Burtsev Dec 27 '11 at 20:52
  • 1
    @AlexBurtsev: If you want it to be public, then yes. On the other hand - now you are using Word .doc files, so you have to put these on a web server as well if you want them public. – Christian Specht Dec 27 '11 at 21:06
  • I note that Sphinx has an "output to PDF" path. – Robert Harvey Dec 27 '11 at 21:15
  • @ChristianSpecht, Wiki and Wordpress have plugins to import Word Doc files. – Alex Burtsev Dec 27 '11 at 21:19
  • @AlexBurtsev: I'm not sure if I understood what you want to do with the documentation. If you want to put it on the web, then you need some kind of web server, no matter if you use Sphinx, Wordpress, a .doc download or something else. If you need to distribute the documentation with shrink-wrap software, you can use Sphinx to generate PDFs or Windows help files. – Christian Specht Dec 27 '11 at 21:26
  • @ChristianSpecht, I want to put it on a private web server, we already use it for Bugzilla, SVN and other tools. – Alex Burtsev Dec 27 '11 at 21:33
  • @AlexBurtsev: Okay, I edited my answer - see above! – Christian Specht Dec 27 '11 at 21:38
  • @ChristianSpecht Menu hierarchies would be nice, we need to link lots of documents, and create ToC's, full text search would be nice too – Alex Burtsev Dec 27 '11 at 21:43
  • @AlexBurtsev: Okay, then Pandoc is not enough and you need Sphinx. It can create ToCs and it has a search function as well (see the Python and TortoiseHG documentations linked in my answer) – Christian Specht Dec 27 '11 at 21:53
  • @ChristianSpecht: having a short look into the Sphinx docs, I think it has *no* search and category functions by itself. What it has is a Web support option to integrate it easily into a search function of an existing web site. – Doc Brown Dec 28 '11 at 08:01
5

Well, you can try to implement a Wiki. Mediawiki has all the missing features you are talking of (search functions, versioning history, links, categorization). You will have to make sure you know exactly which version of the documentation belongs to which version of the software, but that can be done by convention of including a version reference or a specific category in each version dependent article.

BUT: You write you have "analysts" who are not developers (I admit, I am not a fan of that constellation). Those kind of people are often not happy when you replace their MS Office tools by some textual oriented tool like a Wiki. And since MS-Word is not free software, so I guess the requirement "free software" is not really a must. In this situation, a Sharepoint server might be the better alternative. Not free, but AFAIK it has all the features you are requesting, and documents can still be created using Word, Excel etc.

Doc Brown
  • 199,015
  • 33
  • 367
  • 565
  • 1
    We already have a SharePoint server but developers doesn't like it, and don't want to use it (I'm developer myself). We want something where we can easely find information we need. Information that is categorized and linked. – Alex Burtsev Dec 27 '11 at 21:56
  • @AlexBurtsev: I have never used Sharepoint server myself, but I was under the impression that Sharepoint was providing all those features you were describing. But if you prefer a Wiki, Mediawiki will be fine for you. However, you will make some initial effort to install it, define some structure outline, and also define some conventions how to use / not to use it. – Doc Brown Dec 28 '11 at 08:15
  • I'm currently trying out XWiki for its MS Office integration – Alex Burtsev Dec 28 '11 at 09:53
  • @DocBrown - SharePoint is horrible. It's unintuitive, a complete maze of tabs and sub-tabs, and doesn't maintain any proper version control. Anyone using it would be better of dumping all of their docs into a shared directory on an internal server. A wiki is usually the way to go for this kind of thing. – Polynomial Feb 09 '12 at 12:31
2

It is always better to keep specification and documentation under version control as it would give you the biggest leverage though the learning curve would be a bit steep. In case of a knowledge engine, I recommend the following

  1. Trac - Easy to use bug-tracking system and knowledge engine. Written in Python and extensible, you would be up and running in a few minutes
  2. MoinMoin - Full-fledged wiki engine. Again Python with a lot of features

Both have minimal interfaces, supports most of the wiki structures , fairly easy to deploy and maintain, support revisions, has a good WYSIWYG editor and you can even keep your documentation and specification also. Unless your projects are really huge, you could choose any of the above.

Ubermensch
  • 1,349
  • 9
  • 15
2

We recently started using the Alfresco DMS which has a lot of interesting properties:

  • Very simple install
  • Has a built-in indexer for quick searching through heaps of documents
  • Allows work-flows, groups and if necessary, specific access to documents by customers
  • Open-source
  • Active community
  • LDAP/AD/SSO integration
  • Handles many different documents

There are also some disadvantages:

  • User interface is not always intuitive
  • It's not really a wiki, so simultaneous collaborative work on one document might be a bit fragile

If you decide to give it a swing, please contact me with your opinions.

Dibbeke
  • 2,514
  • 1
  • 16
  • 13
0

Another possibility might be to use LaTeX or some other text formater (perhaps texinfo or even lout) for documentation. Parts of it can be machine generated. There are some tools for HTML conversion, like HeVeA to convert LaTeX to HTML. You can also use doxygen to generate documentation from structured comments inside your source code. And the hand written parts of the documentation can (and should) be managed as source code (e.g. w.r.t. version control and build).

Basile Starynkevitch
  • 32,434
  • 6
  • 84
  • 125
  • I'm not talking about software product documentation (help, manual). I'm talking about software specification, business requirements. – Alex Burtsev Dec 27 '11 at 21:21
  • You can write software specification or any technical document in LaTeX, and in some circles it is common practice. – Basile Starynkevitch Dec 27 '11 at 21:22
  • 2
    LaText somehow reminds me of *NIX , and our analysts never herd of such OS -), they live in Windows world, and will not agree on something that is harder than Word for text input. – Alex Burtsev Dec 27 '11 at 21:31
-2

I would suggest using a UML and ERD tool, in addition to your documents. Also, you could store these documents on ZOHO at ZOHO-Docs, which is not free, but it is extremely cheap and allows document search facilities.

Whatever the tool you end up using, you need to organize the document contents carefully to be able to use text search and get meaningful results. Document content organization together with clever and standard file naming could help greatly.

NoChance
  • 12,412
  • 1
  • 22
  • 39