What documents should be stored in version control and how should they be stored?

Question

I've found some similar questions (here, here, and here) asking about storing documents into version control. I have a more specific requirement and general question. The specific requirement is that I want to use Git. The more general question is, how should documents (for design, test, general practices, tips, etc, of a project) be stored in Git? More broadly, what documents should be stored?

I can think of a few ways:

1. Word / Open Office documents. The new Office Word has docx format, which zips up documents, but it also has an unzipped XML format, which could be used to efficiently store diffs in Git. The diff feature is still broken though, since the XMLs are squished on a single line. This is no better than storing a binary file into Git.
2. Wiki. What distributed wikis exist out there? It'd be like some kind of Latex thing where documents are written and compiled / viewed as a wiki.
3. Latex - but from using it for papers I find it pretty unsuitable for documents. Is there a documentation equivalent? (How are man pages written?)
4. Plain text formats, but this is rather lacking due to lack of diagrams, which bring up another point.

How should visuals be stored? What should they be composed in in the first place? I'm developing on a Linux environment, but some other participants in the project are on Windows. What cross-platform solution is there that resembles Visio? And of course, it should not create binary files to be stored into Git. How then would this tie in with documentation? (E.g. Similar to how Latex can reference other diagrams when compiled.)

Answer 1

When deciding what document format you choose, you should make sure that team members (or are you working alone?) are comfortable working with the format itself.

1. Storage is not so much the problem as is being able to see diffs between versions and merging. In my experience, nothing beats text formats that can be edited freely in any text editor. This excludes HTML and about any XML-based format. DocBook being a barely usable exception.

2. A good wiki that can use any of the popular version control systems and be set up in a distributed fashion is IkiWiki. With IkiWiki, markup parsing is done in plug-ins, so you can choose input format on a per-document basis. The "default", Markdown gets pretty close to plain-text formats.

3. If you're unhappy with using LaTeX, don't use it. I think it's unsuitable for taking quick notes. Man pages are written in nroff, but many people use other formats such as POD.

Some projects that strive to be alternatives to Visio are Kivio (KDE) and Dia (Gtk/Gnome). I haven't used Visio itself, so I can't comment on their feature sets. It probably depends on what sorts of visuals / diagrams you want to create. UML? Flow charts?