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?"
I'd have to say... (Score:4, Funny)
Simpler, but at a cost (Score:2)
They tie into a number of commercial document storage systems such as Hummingbird.
But neither will be free (or even that cheap, maybe cheaper than implementing upgrades to Sharepoint.
The simple answer (Score:5, Informative)
There's plenty of WYSIWYG tools for Latex. Let Google be your guide.
Simon.
Comment removed (Score:5, Informative)
Re:The simple answer (Score:3, Funny)
Just like Linux productivity jumped when people stopped wasting any time talking about pronouncing it "lihnuhks" vs "lienuhks".
Re:The simple answer (Score:3, Insightful)
Re:The simple answer (Score:5, Informative)
Not true. The OP asks about version control and branching... and the best way to store something for version control is as plain text. Yes, modern version control software allows fairly sophisticated binary deltas (for example, I believe SVN has this capability) but there are still features that can't be done without text.
For example, can your version control software tell you what text changed between two revisions of Word documents? It can if they're LaTeX documents.
Re:The simple answer (Score:2)
And even if you're right, you don't need to switch to LaTex to have plain text files. All word processors, including Word [wikipedia.org], have plain text formats.
Re:The simple answer (Score:2)
That is a reason to use LaTeX or similar markup scheme which promotes separation of content from styling. I don't know much about DocBook, so it may be an even better candidate for that sort of thing.
Using RTF from may be feasible, but from what I remember its RTF output is just as ugly as its HTML. It would be horrible to use with diff.
Re:The simple answer (Score:2)
Re:The simple answer (Score:4, Informative)
Re:The simple answer (Score:2)
Since LaTeX is, beneath the hood, TeX, you can't predict how free from formatting specific markup the document will be.
Can you write LaTeX files without formatting information in them? Yes. I've rarely seen one, though.
Re:The simple answer (Score:2)
Very true! That's why I encourage people to look at DocBook [oasis-open.org]. I've been using it for over a year now in lieu of LaTeX for documents ranging from simple HowTos, to design and specification documents, and some nearly book sized projects.
Paired with a sensible XML editor, you can be very productive!
Re:The simple answer (Score:2)
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.
Re:The simple answer (Score:2, Informative)
Only if the author sucks at writing LaTeX, and does things like this:
When they should be doing things like this:
A LaTeX document, used properly, does not have any styling information in the document -- that's the job of the document class, and possi
Re:The simple answer (Score:5, Informative)
Actually, switching to LaTeX changes the scope of the problem from tracking changes to arbitrary files to tracking changes to text files. There are a lot more tools that are good for the latter problem than the former, so the available options get bigger. You're right that it doesn't suggest a good tool to go with, though.
Re:The simple answer (Score:2, Insightful)
Re:The simple answer (Score:5, Insightful)
I love LaTeX (I have TeXShop [uoregon.edu] 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.)
Re: (Score:2)
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:The simple answer (Score:2)
Re:The simple answer (Score:2)
That's a matter of perspective. Using Word, you couldn't produce the kind of LaTeX'd documents I've seen in fields from mathematics and software engineering to linguistics, no matter how long you tried. And for that matter, someone competent with a tool like LaTeX will generally be far more productive doing a task that suits it than someone competent using a tool like Word.
As I've commented here several times before, it's a mystery to me why no-one has got wise to this and filled the rather large gap betw
Re: (Score:2)
Re:The simple answer (Score:2)
Yes, and they certainly have their merits. But really, they're not even on the scale of what I'm envisaging here (which is closer to a package with WP ease of use, DTP levels of page layout and typography tools, LaTeX levels of support for templated content and document structure, and a plug-in model for incorporating non-textual content).
This is one of those really annoying things, where I've developed quite a detailed vision after many sessions of thinking about this subject, I have the technical abilit
Re:The simple answer (Score:2)
Perfectly true. But, beside the point, since the person who asked the original question could give a shit. LaTeX's cool formatting fea
Re:The simple answer (Score:2)
Comment removed (Score:4, Informative)
Re:The simple answer (Score:2)
How did you know what languages I had in mind? I was talking about Tamil or Devanagari. Current solutions don't handle ligatures very well, if at all.
Actually, I find (La)TeX sub-par even for accented Latin (as used in IAST, for example). I don't want to have to treat combining characters differently from regular Latin.
Re: (Score:3, Insightful)
Re:The simple answer (Score:2)
Now you're just back-pedalling. I have to typeset Devanagari and Tamil. I don't use software that cannot handle it easily. LaTeX, otherwise well-designed, doesn't cut it. So I don't use it anymore.
BTW, lots of UTF-8 software do handle Devanagari/Tamil. Software that don't do any rendering handle it just fine, like bash, vim and most of the GNU utils. On Linux, the ones that do rendering mostly
Re: (Score:2)
Re: (Score:2)
Re:The simple answer (Score:2)
Well, sorry, I'll call you on that one, then. A friend of mine typeset an entire Masters thesis with plentiful Hindi quotations using LaTeX, because none of the mainstream WP software was up to the job. We even designed a whole new font with METAFONT, containing most of the major Devanagari glyphs, and mapped to standard roman transliterations.
This obvio
Re: (Score:3, Informative)
Re:The simple answer (Score:2)
GNU TeXmacs is one that I've recently discovered, and it's quite nice. It's especially good if you want to incorporate sessions with programs like gnuplot, octave, or guile into your documents. (For example, if you type "plot x**2" while in gnuplot mode, the graph produced becomes part of your document, just like in Mathematica.)
It's also good for your other daily typesetting needs.
Re:The simple answer (Score:3, Insightful)
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.
Re:The simple answer (Score:3, Informative)
I've written many collaborative documents in this manner. One involved people across 2 continents, 7 institutions, Linux, OSX and MS Windows, a tight deadline, strict government formatting requirements, and noone with enough time to merge the whole thing.
One simple makefile, and anyone could do at anytime
svn update
make pdf
and check that the final PDF was in tiptop agreement with the NIH formatting guidelines
Re: (Score:2)
Subversion... (Score:5, Informative)
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.
Re:Subversion... (Score:2)
It handles binaries right (unlike CVS)
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.
Re:Subversion...[*Does* Call Binary Diff Tools] (Score:5, Informative)
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 [tigris.org] 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.
-MallocRe:Subversion...[*Does* Call Binary Diff Tools] (Score:2, Interesting)
Thanks, this is great news.
Re:Subversion...[*Does* Call Binary Diff Tools] (Score:2)
Re:Subversion... (Score:2)
Re:Subversion... (Score:3, Insightful)
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
Re:Subversion... (Score:2)
Re:Subversion... (Score:2)
We have that but convincing the non-coding guys that a problem even exists is the real challenge. I am going to lose this one.
Re:Subversion... (Score:2)
I suggest you start by committing everything into SVN and using it for yourself (like commit other people's changes as "misc other people changes" and then commit your own changes with real commit messages), if only to prevent you from being annoyed by the issues it brings.
Then you can start evangelizing.
Re:Subversion... (Score:3, Interesting)
Explain what you mean be "distributed" (Score:2)
I don't know how other SVN clients work, but we use an SVN server and Eclipse clients with the Subclipse plugin. The effect is that you login to Eclipse and sync whatever files, directories, or parts you want, and it copies them to your local filesystem. You can then open them in Eclipse (online or offline) but you can ALSO open them using your favorite filesystem tools, including grepping them. The current tree is completely distributed, and you never ever need to s
Re:Subversion... (Score:2)
I support this completely
Also, when you run a diff on an M$Word document, it acually loads a MSWord Diff version so you can graphically see the differences in the document. Not sure if OOo has this yet...
JsD
Re:Subversion... (Score:2)
Re:Subversion... (Score:5, Informative)
I love it that much, and you can too!
Re:Subversion... (Score:2)
In summary, it has the following features:
Re:Subversion... (Score:3, Informative)
Re:Subversion... (Score:3, Informative)
SmartSVN [syntevo.com]
Back when I was looking at SVN clients, I found this one had the most promise. Of course, if you have users who know Windows Explorer (assuming your site is MS-based), then TortiseSVN [tigris.org] is another good alternative.
Re:Subversion... (Score:3, Informative)
Make them read this http://svnbook.red-bean.com/ [red-bean.com]
Wait, scratch that... FORCE them to read it...
I've been using it (okay, I'm not in any Big Projects as we speak, but i've tried it), and it can be mostly simplified to svn update && svn commit for most of the time...
Re:Subversion... (Score:3, Insightful)
Re:Reasons _NOT_ to use subversion: (Score:4, Interesting)
- PeeCee
Question I ask my coworkers too (Score:2, Informative)
When another user decides to edit it, they'll see that it's "checked out
Re:Question I ask my coworkers too (Score:2, Informative)
http://www.sugarcrm.com/ [sugarcrm.com]
Re:Question I ask my coworkers too (Score:2, Informative)
In a nutshell: You set up the central repository, and then everyone who might work on a file maps a directory to this trunk. Whenever you make a change to a document, you check that in to the central Subve
Sharepoint has revisioning (Score:2, Informative)
Doing this keeps previous versions of the document. If you just open, edit & save, then you're just updating the current version of the docume
Re:Question I ask my coworkers too (Score:2)
Many businesses -- even "most" -- are going to keep their important documents in Word...period. (I'm a vim/svn guy myself, so don't bother preaching to the choir.) The real question is, if use of Word itself is a requirement (as it very often is), then how can you add proper revision control to Microsoft Office?
By way of answer, I'm going to make a totally biased plug for my brother's product, DocumentLocator [documentlocator.com], which is designed to do exactly that.
All-encompassing tools (Score:4, Informative)
While I haven't managed to get them integrated into the workflow yet (working on it), I find tools such as Trac [edgewall.com] 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.
Re:All-encompassing tools (Score:2)
Precision to my previous post: when I say that I haven't managed to get them integrated into the workflow, it's not in the technical sense of the term (installing Trac is fairly trivial) but in the hierarchy-related one, management isn't interrested in changing it's habbits or in seeing the dev teams change their habits.
Non-binary formats (Score:2)
Amen to that. One of the nicest things about non-binary formats is the ability to difference versions without any special tools.
Trac (Score:3, Informative)
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.
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 t
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.)
Re:Baby step #1: source control + existing docs (Score:2)
Trac and Subversion (Score:2, Redundant)
Meta-answer (Score:5, Informative)
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.)
Re:Meta-answer (Score:2)
What is the problem with keeping specs in Sharepoint and code in SVN?
Sharepoint is really good at tracking/merging Word docs. SNV is really good at tracking/merging text files. Why not use both?
Ease of Inertia (Score:2)
Talk to End Users (LaTeX+subversion vs. Mediawiki) (Score:2)
That being said, it is not usable if you're dealing with end users who don't understand the tools. Your FAs sound like such users. The front ends for LaTeX have scared end users and/or write pretty bad LaTeX (which causes those who hack it in vim to screa
Trac/Subversion + Knowledge Tree (Score:3, Informative)
For managing Documents I would use Knowledge Tree [ktdms.com]. The open source version is cool and the professional edition adds in all the stuff managers like.
Microsoft Word and Sharepoint (Score:4, Informative)
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.
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.
SVN + WebDAV + Autoversioning (Score:5, Informative)
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."
Mod Parent Up. Was Re:SVN + WebDAV + Autoversio... (Score:2)
Re:SVN + WebDAV + Autoversioning (Score:3, Informative)
Go Wiki, go Confluence (Score:2)
Everything your analysts like about the combo of Word and Sharepoint will be provided in an easy to use package, plus everything that the "geeks" want, need, and love will also be provided.
Yours,
Jordan
Confluence fits your requirements (Score:3, Informative)
Lucidoc (Score:3, Informative)
Telelogic's Doors (Score:2, Informative)
Brian
Go for Alienbrain (Score:2, Informative)
Short and Sweel (Score:2)
Twiki.org (Score:2)
text source for documents. (Score:2)
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:
Why branching for spec documents ! (Score:2)
Unless your spec is hundreds of pages long, I dont see a need for branching
Do not overkill
Word has this built in (Score:5, Informative)
Re:Word has this built in (Score:4, Informative)
I use the comments stuff heavilly myself though, very useful to mark and annotate work-in-progress.
Subversion + Trac (Score:3, Insightful)
use subversion (Score:3, Insightful)
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.
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?
Re:Probably not helpful at all, but what I do... (Score:2)
Re:Good luck (Score:2)
I don't offer these comments unkindly. The fact that you had the will to make things better is praiseworthy. But making things better is not just about your indulging your personal opinion. A Wiki exists to serve the needs of a community, after all. Now that you know who