Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I'm starting up a Git repository for a group project. Does it make sense to store documents in the same Git repository as code - it seems like this conflicts with the nature of the git revision flow.

Here is a summary of my question(s):

  • Is the Git revisioning style going to be confusing if both code and documents are checked into the same repository? Experiences with this?

  • Is Git a good fit for documentation revision control?

  • I am NOT asking if a Revision Control System in general should or shouldn't be used for documentation - it should.

Thanks for the feedback so far!

share|improve this question

migrated from serverfault.com Jun 17 '11 at 20:24

This question came from our site for professional system and network administrators.

    
Ah, okay... thanks for the clarification. I don't see why it would be a problem, but I don't have any personal experience with GIT (just a theoretical understanding), so I'll let someone with more direct experience answer that question. –  Flimzy Jun 17 '11 at 7:24
1  
I don't quite see how this is on topic. You're talking about software documentation and committing with a DVCS –  Tim Post Jun 17 '11 at 9:36
    
Probably depends on the documentation and your needs. Do you need diffs and is it in a format that can handle it? If git gives the required services sure. Beats having a separate document management system... –  Rig Mar 15 '12 at 11:33
    
If your documentation is in plain text - fine. If it is a binary format, you essentially need a version control system that understand the binary format - this is vendor lock-in in its purest form. –  user1249 Sep 8 '12 at 9:20
    

8 Answers 8

We store documentation in SVN all the time. In fact, our entire user manual is written in LaTeX, and stored in SVN. We chose LaTeX specifically because it is a text-based language, and easy to show line-by-line diffs.

We also store some non-text formatted files, like Microsoft Office .doc files, spread sheets, .zip files, etc, when necessary... but some of the benefit of a RCS is lost when you can't see the the incremental diffs.

The key is really to make sure your documentation is well organized, so that people can find (and update) the documentation (and the source) when they need it.

share|improve this answer
    
@cstamas, optimize your answering speed? –  user1249 Jun 17 '11 at 12:51
11  
If you're a Microsoft shop, TortoiseSVN supports MS Office line-by-line diffs. –  Phil Jun 17 '11 at 13:46
1  
Dropping binary doc formats would make the world a better place. o given that docs are plain-text, there should be no real problem with a DVCS either. –  Kai Inkinen Jun 17 '11 at 18:28
    
Oh, and first time I heard about TortoiseSVN and doc files, so +1 for that. Wonder if that'll end up on Tortoise[AnyDVCS] anytime in the future. –  Kai Inkinen Jun 17 '11 at 18:28
    
@Phil: How does TortoiseSVN accomplish this? Is the doc-diff viewer integrated with the SVN client, or can it be used independently? –  Flimzy Jun 19 '11 at 6:13

Well it depends on what format do you use for the documentation. If it is something text based it is all good.

Git can also store binary content and you can track revisions, but the diff output will not make sense.

It is also possible to store documentation in the code itself like perldoc pod, java also has some format/annotation for this.

share|improve this answer
    
I agree, while it's possible to store non-text documentation, git will do a lot better if you store text instead. There's been talk of a diff driver that knows how to diff word (or similar) documents, but I'm not sure if it was implemented or not –  Sverre Rabbelier Jun 17 '11 at 9:27
    
I though Word moved their format away from binary to XML. –  chaz8705 Jun 17 '11 at 13:48
2  
@karategeek6 Word's 'XML' format is not human readable. And one line of text does not correspond to one line of Word's XML, even in approximation. So it might as well be binary. –  Myrddin Emrys Jun 17 '11 at 13:56
    
@Myrddin Ok, thanks for the info –  chaz8705 Jun 17 '11 at 14:08
    
You can instruct Word to save your output in uncompressed XML. Choose Save As, then select Word XML Document (*.xml) instead of the default Word Document (*.docx). The XML is pretty complex, so this is no guarantee the changes will be easily readable, but at least it won't be binary. –  Kyralessa Aug 17 '11 at 17:06

I can't imagine why you think there might be a problem using git, or any other version control system, for documentation. Just like source code, documentation should have a full history and the ability to revert to an earlier version if that becomes necessary. A version control system is perfect for this.

share|improve this answer
3  
Only if the documentation is in a text form. Binary blobs do not fully benefit from version control. –  user1249 Jun 22 '11 at 8:00
1  
@ThorbjørnRavnAndersen: Even so, unless you have a binary-specific versioning system, it's probably better to keep even binary files in Git rather than on their own. –  Tikhon Jelvis Sep 8 '12 at 17:24
    
@TikhonJelvis I did not question whether it is a good idea to put binary files in git - if they are the original artifacts, it is. Try, however, to run "git diff" on Word documents. –  user1249 Sep 8 '12 at 17:46

It is clear that using some kind of Version Control System for storing docs is a nobrainer. The more interesting part of the question is if it is good idea to store documents in the SAME location as the source code? The possible problem here is that it might be hard to set different access privileges for code and documentation in that case. And in many business cases people will need access to docs but not the source code, like marketing or BA departments.

share|improve this answer
1  
Yes, the "same location" aspect is one of the key parts of this question! –  EmpireJones Jun 17 '11 at 18:13
    
Same location is good if you can manage it, because it avoids the need to either have tribal knowledge (knowing where to look), or the need to go searching for where the stuff is. –  quickly_now Jun 22 '11 at 8:06

In the company that I work we put documentation in SVN. However, after few conflicts and the need to share it, we decided to move it to Mediawiki.

At first it was trac, after that moved to Mediawiki cause it was easer to use...

The main problem with SVN was the sharing cause we had authorization system for SVN.

share|improve this answer
2  
Don't you mean Mediawiki, the wiki engine that Wikipedia uses? –  Martijn Heemels Jun 17 '11 at 18:49
    
@Martijn, I'd assume so –  Teo Klestrup Röijezon Jun 18 '11 at 0:57
    
@Martijn: Yes, edited –  confiq Jun 22 '11 at 7:55
    
I would rather stick with a wiki rather than sending a lot of files that are not course to a SCM, but thats more to do with personal preference. There is much more you can do with it. I specially like Foswiki and their website based/ project based template. Glad someone pointed deciding to use a wiki due to problems :) +1. –  Oeufcoque Penteano Mar 15 '12 at 12:49

I came here with a similar question. We come from a SVN-environment, where it basically is a no-brainer to keep all materials related to a project in the same repository. Due to SVN's nature, you can easily check out parts of the repository, so if you just need the sourcecode (for example, a website deployment), that's no problem.

With Git, things are different. A checkout is always at the root level, so if you want to put everything in the same repository, you will always end up with the same directory structure. One approach I have come across is to put everything in separate branches, i.e. you have code-branches (which would typically be your normal master, develop, etc. branches) and a doc branch, which has its own, separate directory structure. I'm not certain yet that's the best idea, but it is a suggestion which circumvents the problem which I imagine is at the base of your question.

share|improve this answer
  • Having more than just source code in a repository is a very good thing.

    It groups all of your resources together and turns the project into a cohesive, centralized entity rather than a scattered collection of files. Contributors/employees know where to find everything, rather than sending "Where do I change the documentation for feature x?" emails.

    You'll want to keep things organized. Have a system for separating the src from the images from the docs. You can always add a .gitignore to a directory to keep the repository and history clean. Because Git commits are file-based,* you can decouple source changes from documentation changes as strongly as you like.

  • As others have said, Git is great for documentation versioning as long as it's text-based.

  • I completely agree; documentation should be versioned right alongside the code.

My credibility comes from being a GitHub user and contributing to one project and exploring many others. In my experience, a complete, unified project is easy to tell from a half-missing one. I try to contain all of my projects within single directories whenever possible.


* This isn't quite accurate, because there are ways to specify parts of a file to be committed (here's one example).

share|improve this answer

I use a wiki for internal docs...get revision PLUS prominent access/easy editing. When documentation is out of sync, update it right then and there. For end-user documentation, consider a professional tool like Madcap Flare They use an XML dialect for sharing, composing, and transforming documentation.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.