Document Management and Version Control? 326
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?"
Baby step #1: source control + existing docs (Score:5, Interesting)
It's pretty shocking to change everything (document format, writing environment, collaboration tools) all at once. Start with reasonable source control, the best bacon-saving device you can get. Have everyone check existing docs (Word, HTML, whatever) into source control; Even though diffs are meaningless for the binary formats, the other benefits (versioning, collaboration, remote storage, tags, platform independence) are huge. It's the quickest way to put an end to the madness of emailed .doc files and accidental deletions.
If you've got a lot of Windows users, go with Subversion [tigris.org] and get everyone to install the TortoiseSVN [tigris.org] shell extension, which offers the most natural GUI for new (and experienced!) users of version control.
Once everyone's comfortable with SVN, you can then start migrating to text-based document formats in which the source control diffs mean something (LaTeX, XML, reStructured, etc.)
Requirements Management (Score:1, Interesting)
Re:ODF + SVN: auto unzip and rezip? (Score:4, Interesting)
The diffs might still be more usable than those for a 100% binary (zipped) file, particularly for single-user situations.
Has anyone played with compressing/decompressing ODFs for use with version control software? Any pointers?
Depends very much on your analysts (Score:5, Interesting)
When our "functional analysts alike" guys wanted version control, we naturally gave them the tried-and-tested CVS, and gave them instruction on its use. It was a horrible failure. The update-edit-change-commit cycle which is so trivial to developers just didn't work. The people are not dumb - just have a different mindset. We had also tried a Wiki (MoinMoin, works well for devs), but its inability to search or version Excel files make it irrelevant.
Eventually, much to my dismay, we settled on Sharepoint. And while it's clunky, horrible, keeps only the 7 latest versions of any file, has no branching and is often inconsistent with error messages, them users are able to work with it without requiring assistance.
Do not confuse a feature list with applicability of a tool to the situation at hand which, it appears, might depend more on the people involved than anything else.
Re:The simple answer (Score:3, Interesting)
Sorry, I over-generalized "WYSIWYG tool [for LaTeX]" to WYSIWYG document processor. You're probably right that graphical LaTeX editors aren't substantially more accessible than the bare LaTeX markup.
[Aside: Where are these men-on-the-street who need all this professional typesetting? I want to live on that street! My car probably wouldn't get broken into as much.]
Re:Trac (Score:3, Interesting)
But I do agree, Trac is a great tool. Combination of wiki + ticket tracker + roadmap + svn browser. It's great because it's all integrated: you can make wiki posts that say "this will be done in milestone:1.2", tickets that say "Fixed in [265]" (revision), or svn commit messages saying "Fixed ticket #23" and everything becomes a link (see: http://projects.edgewall.com/trac/wiki/WikiFormat
The wiki may or may not be an answer to the submitter's question (for the analysts), depending on how closely related the documents are to the code, and if they can get the analysts to switch from word to wiki syntax.. but it's definately worth checking out. So far everyone I've introduced trac to loves it.
Re:Subversion...[*Does* Call Binary Diff Tools] (Score:2, Interesting)
Thanks, this is great news.
Svnwiki, of course (Score:5, Interesting)
I would suggest using svnwiki [freaks-unidos.net], a wiki system that stores its whole contents in a Subversion repository (Disclaimer: I am the main author of svnwiki). That allows you to use the usual svn commands (svn diff, svn log, svn update, etc.) to work with your wiki as well as using the web interface.
You can see an example wiki [bogowiki.org] (in spanish) and its associated svn repository [no-ip.info] (login as anonymous, password is the empty string; Slashdot seems to strip out this auth information from my URL) to get an idea of what the repository looks like.
These are examples of some of its features:
Re:The simple answer (Score:5, Interesting)
We use DocBook XML for the source format of the MySQL Manuals, and SVN for version control. We maintain 3 distinct versions of a >1600-page software manual this way, in numerous translations. We produce end-user docs in HTML, PDF, TexInfo, plaintext, CHM, and a couple of other formats. These include the online manuals at dev.mysql.com which get updated 4 times a day from our SVN repositories. We also maintain the Internals Manual using this system. It's also relatively easy for us to produce documentation that's either standalone or integrated with larger documents, such as the Connectors manuals.
We are very happy with this system. Our users seem to be also.
I use oXygenXML as my principal XML editor. So do some of my teammates. It's thoroughly DocBook-aware and does nice transformations of shorter DocBook documents into HTML and PDF. It also validates, pretty-prints, and does a good job performing diffs and merges between different versions of large (100+ K) documents. (It also provides for editing and debugging XSLT stylesheets, although I don't personally use it for that at present.) It's available on *nix, Windows, and Mac (yes, it's a Java GUI app, but it's remarkably fast and stable one). It's neither libre nor gratis, but it's well worth the money, and much cheaper than the (other) commercial alternatives. If you are working hands-on with large amounts of XML in a production setting, I strongly recommend that you check it out.
Try KTDMS (Score:2, Interesting)
http://www.ktdms.com/ [ktdms.com]
regards
libregeek
Re:Reasons _NOT_ to use subversion: (Score:4, Interesting)
- PeeCee
Re:Subversion... (Score:3, Interesting)
Re:Explain what you mean be "distributed" (Score:2, Interesting)
You got it wrong. Or got only half of it. Sharing is a double edged knife: it can hurt as much as it helps.
To explain it simply, decentralized systems allows me to have local intermidiate version of file. In centralized system, if I want my changes be protected or simply numbered (so I can rollback later), I have to commit working files into repository.
If my changes are at very very early stage and not yet ready for general use, commiting would force others to do additional steps to avoid using my new (raw, broken) version of file. If there are many commiters like that - and that's pretty normal with huge source code repositories - the life can easily become nightmare. (*)
Decentralized version control allows you to have local repository. And consequently, it allows you to commit you changes to your repository. It doesn't forces my changes on everyone before proper time X, but allows involved people to pull changes directly from my local repository and for example to test their own changes along with my ones.
When time comes, I can submit all changes from my local repository to global public one.
P.S. Another good use for decentralized version control, is disconnected work. If you are with your notebook in office - you can commit. At home - with centralized repository in office - you can't. With decentralized system - you can commit directly on your notebook, and later on when reaching office, commit changes from notebook made over week-end.
(*) That's the reason why in centralized systems, changes are very big - people tend to commit less to avoid needless breakage. In decentralized systems changes are often small and abundant. You can afford the luxury.