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?"
Shoot the functional analysts. Once that's done, there won't be any complaining, and you can use CVS. Extreme, but simple.
"Murphy was an optimist" - O'Toole's commentary on Murphy's Law
Latex with CVS. This is what I use for my documents. It's simple (yes it is simple.. markup languages are not hard to understand) and with CVS it's far more feature complete than Word in version control.
There's plenty of WYSIWYG tools for Latex. Let Google be your guide.
Simon.
Subversion is your friend...
It handles binaries right (unlike CVS)
It works over a variety of transport layers (HTTP/HTTPS/SSH) with some decent authentication models.
It treast revisions as an archive-wide property.
You can't check in an inconsistant state.
It runs under *NIX, Mac, Windows, etc.
Its free software.
Try it. I switched a few months back from CVS and have been very happy.
Test your net with Netalyzr
Someone replied: "Ever heard of Adobe Acrobat? That's what it's for." I'd like to say they missed the point of the question, which isn't just edits to a document. What I think the poster, and myself, are searching for is a web-based document server that tracks who's working on what, when. So if I decide I'm going to work on the Abstract of a paper, I go online, download it, and work on it. Let Word or whatever track my exact edits.
When another user decides to edit it, they'll see that it's "checked out" and that they should work on something else, or contact me to continue with my edits. This avoids people working on the same document. Version control. It doesn't have to be complex to the end user, but I think the behind-the-scenes work for tracking uploads and downloads, different document piles, etc, would be extensive.
While I haven't managed to get them integrated into the workflow yet (working on it), I find tools such as Trac extremely interresting and full of potential: Trac integrates a wiki (for base documentation) with a bugtracker (bugzilla-like) and a Subversion repository while linking all of them together (you can use the SVN commit comments to link a commit to a bug, track them from the wiki, generate timelines, ...)
And important document should never ever be stored in proprietary binary formats: you can't decrypt them yourself, can't change bugs, can't do anything.
"The way we can tell it's C# instead of Haskell is because it's nine lines instead of two." -- wadler
I myself like using trac which I believe is opensource and works off of a subversion tree. To my knowledge Subversion is meant to be a better solution then CVS for most items, and can be used on it's own.
On the other hand, my company uses Subversion and TortoiseSVN as a shell extension, edit files locally and simply commit them to the subversion repository. You can do all the blame, branching/tagging you need, but our company is likely much smaller then yours. Something to look at I guess.
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 and get everyone to install the TortoiseSVN 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.)
I doubt I'll have much to add to the long list of people describing their experiences with various systems, but I'll pop out this meta-thought: Your developers and "functional analysts" probably have wildly varying needs, especially if the "functional analysts" use word-processing documents like Word. There's no crime in given each group of people a separate system.
Your devs probably ought to get subversion because the continuing cost of using a sub-optimal source management system adds up to staggering amounts pretty fast. Your other writers probably aren't continuously branching and merging and doing all the other things subversion allows (if nothing else that's really confusing for most documents), so they can use a simpler, easier-to-use system that doesn't incur continuous costs due to confusion and documents getting mangled or destroyed due to incorrect use of the system.
The right tool for the right job.
(Note: I'm not saying you should use multiple systems; I'm just saying it's not a crime, if they solve different problems. If you can get your writers to use SVN, especially if they use something with a decent plaintext representation that stands a chance in Hell of merging, hey, great, more power to you.)
Many have mentioned Trac/Subversion allready and I second that.
For managing Documents I would use Knowledge Tree. The open source version is cool and the professional edition adds in all the stuff managers like.
We suffer more in our imagination than in reality. - Seneca
Based on the requirements, you should be using Microsoft Word and Microsoft Sharepoint.
If those don't fill your needs, then either you've failed to describe your requirements or you've failed to correctly set up the software.
ODF files are just zip files which contain the content in an XML file with supporting text and binary files. The text files are auto-generated & so may have "weird diffs" particularly when multiple people/programs/platforms work on them. I have an ical server backed by subversion's webdav & the diffs are always very amusing, as each program changes whitespace & other such nonsense.
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?
Where I work, developers use CVS exclusively. It has its quirks, and we've considered alternatives, but the combination of CVS+TortoiseCVS+Jalindi Igloo (Visual Studio integration)+Jira is unbelievebly hard to beat (Subversion doesn't have a reasonable SCC connector, and nothing else has anything that comes close to TortoiseCVS -- even TortoiseSVN is clunky and awkward by comparison. Oh, and CVS mergepoints work perfectly, unlike the nonexistent merge tracking capabilities of Subversion).
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.
http://svnbook.red-bean.com/nightly/en/svn.webdav. autoversioning.html
From the SVN Handbook:
"Because so many operating systems already have integrated WebDAV clients, the use case for this feature borders on fantastical: imagine an office of ordinary users running Microsoft Windows or Mac OS. Each user "mounts" the Subversion repository, which appears to be an ordinary network folder. They use the shared folder as they always do: open files, edit them, save them. Meanwhile, the server is automatically versioning everything. Any administrator (or knowledgeable user) can still use a Subversion client to search history and retrieve older versions of data."
The poster says they're using Sharepoint. It already has the capability to "check out" a file instead of just opening and saving it. Click the down-arrow next to the document name and select "check out". The document list will then update to show that you've got the document checked out. When you've edited and saved the document, do the same and select "check in".
Doing this keeps previous versions of the document. If you just open, edit & save, then you're just updating the current version of the document.
Of course, Subversion is no more your friend than CVS in this case since neither can do proper diffs! It's binary data for f*ck sake! Subversion handles binaries better than CVS, but not for the reason you state.
Actually, GUI Subversion clients like TortoiseSVN can show diffs for binary files like Word or OpenOffice, using the built-in diff capability of these programs. The end result is you can double-click your binary document and get a window showing you the differences.
The latest nightly TortoiseSVN builds even include an image diff viewer.
-Malloc___________________ I want to be free()!
- WYSIWYG editor built in with an option to do wiki-markup if you want.
- Full versioning of the docs and attachments
- Full searchable indexing of both docs and attachments (even word, powerpoint, excel, and pdfs)
- Customizable navigation and templating
- Easily customizable permissions
- It works great with open-source databases (postgres in our case) and pay ones and its searching is very powerful
- You can be set-up and running in about 30 minutes
My favorite feature is that we don't have to mess with it at all. We set it up and both non-developers and developers get along with it well. I would chose it over Sharepoint or Notes in a heartbeat (both of which I used before and thought were a mess).It sounds like you want something like Lucidoc. It integrates with Word and even IE, and does what you seem to want, I believe. It's pretty seamless, and used in health care document systems. Have a look at it and see if it does what you want; it sure would be easier than convincing MS Word users to use cvs or svn. Disclaimer: I am neither a vendor nor a user of this stuff, but I know one of the developers.
The Signal/Noise ratio can be improved in two ways. Remaining silent is the OTHER way.
We use Telelogic's Doors It's good for large projects with multiple systems. It supports requirements tracability and revision history to the object (typically a paragraph). After you're done you can export it to MS Word and you can customize this process using a scripting language and Word templates. I work for a government contractor and the systems we develop include hardware and software efforts on multiple independent processors. It might be overkill for what you need.
Brian
Having individuals on the team without a development background and/or the need for a decent UI and all the features you could ask for in a version control system, I'd urge you to get your hands on Alienbrain. It is stable, easily accessible for non-techies, industry-proven and still the market-leader in game dev. You could of course look into UIs for subversion etc. but I guess something along the lines of Alienbrain would be most feasible in your case. And for the rest set up a wiki.
I would suggest using svnwiki, 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 (in spanish) and its associated svn repository (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:
Alot of people don't realize it, but there is document versioning built into Word. If it's turned on, it will track changes, etc. by user. There is also pretty rich editing capabilities. Reviewers can mark up the doc with comments, etc... Adding sharepoint lets you distribute that process pretty well. Get an in-depth Word book and figure out how to do it in sharepoint/word.
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
Try KnowledgeTree Document Management System. It will allow to use any document type and organize it on a common location. It can also search within PDF, MS Documents and OpenOffice.org documents.
http://www.ktdms.com/
regards
libregeek
- PeeCee
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.
All hope abandon ye who enter here.