Slashdot Mirror
Document Management and Version Control?
Tom wonders: "I am working in a medium-sized software development company. The functional analysts use Microsoft Word to document the specifications, and Sharepoint to publish the documents. However we'd like to improve our process to have better revision control and traceability. We have looked at alternatives like using Wikis, or static HTML documents with CVS. The functional analysts want ease of use, while we developers would like to see high-quality end products, revision control (i.e. tagging & branching of the document base), and traceability features. What tools and document formats do you use and would recommend?"
LaTex may be terminally cool for creating fancy-looking documents. But it doesn't solve any problems that this guy cares about. For his purposes, it's just another word processing format.
I love LaTeX (I have TeXShop open in the background right now!), but I have to argue with the assertion that the uninitiated "man [or woman! -ed] on the street" can be just as productive as s/he was in Word. Compare Word's graphical table builder and tab ruler, the result of about 20 years of noodling around with the best user experience for creating such things, with \begin{tabular}{|r|r@{.}l|}. OW MY WORD PROCESSOR.
Even if you give everyone a pocket syntax reference, unless you have a TeX ninja working overtime on your templates, you'll still end up with a lot of documents that look like academic research papers. This is fine if what you're writing are academic research papers [hi!], but for most corporate communication people are accustomed to more effortless (read: WYSIWYG) control over the output. (This is, of course, usually a terrible idea, resulting in official RIF memos from HR written in Comic Sans; I think there's a happy medium somewhere in between.)
There's plenty of WYSIWYG tools for Latex
No, there aren't. If you believe a WYSIWYG tool is possible for LaTeX, then you either don't understand LaTeX or you don't don't understand WYSIWYG.
I have been moved on to a new project to develop a user interface in Java. I have java development skills but my job is to write UI specs in word and visio. The developers use SVN for their code and somebody checked the documentation tree (where I and three other engineers work) into SVN.
But the people I work with (systems engineers, in our terminology) rely entirely on windows explorer and email to manage their documents. They have a complex file naming scheme which is always breaking. They have to manually sync with one off site engineer by email. Word locks documents for read/write if it can so you have to ask people to release documents for your control.
I have suggested several times using SVN to manage documents but none of my fellow workers will have a bar of it.
I am not a fan of SVN myself, I prefer totally distributed systems, but in this case it would be the right tool to use.
http://michaelsmith.id.au
See my response to somebody else who said pretty much the same thing you did.
Most UTF-8 software doesn't handle Devanagari well. LaTeX is hardly in the stone age compared to other programs.
Accented Latin doesn't require combining characters, since macron-ed vowels are distinct characters in Unicode. When I write a LaTeX document with Latin, I enter all characters in just plain, direct UTF-8.
TortoiseSVN. Seriously, try it, it's extremely good, fairly stable, and features a high integration to Windows Explorer (with nice icons to boot) which means that your user don't have to learn a whole new software: they're working in a familiar environement with just some more items in their contextual menu.
"The way we can tell it's C# instead of Haskell is because it's nine lines instead of two." -- wadler
I second all the Subversion recommendations, and add to that the web-based Trac frontend. Trac incorporates a web-based interface to your SVN repository, along with authentication & access levels, wiki, and several project-management features (timeline tracking, milestone tracking, ticket system, etc.) Nice interface to SVN, though you should still install Tortoise on everyone's desktop for additional client functionality. Here's an interesting writeup on one sysadmin's use of SVN, Trac, and RapidSVN client.
Flying is easy, just throw yourself at the ground and miss. -Douglas Adams
The reason I'm recommending subversion is because I strongly believe that development artifacts should be kept as close to the source code as possible (so when you branch or tag these artifacts are part of the operation instead of out of date binary blobs on some network drive). Since we are talking about functional specifications here that means storing them in a source repository and as far as I can see subversion is the best option. It supports efficient storage of binary files; easy integration with windows explorer; easy esposure through an intranet or even over internet via ssh or https; integration with webdav etc.
Do not use cvs. Period. There are no use cases left where cvs is better than subversion. Even the tooling now is comparable or better for subversion (e.g. tortoisesvn is much nicer than tortoisecvs) so the legacy tooling excuse for using cvs is no longer valid.
Jilles