17

Everybody knows that well-documented software development leads to success. However, it usually means that not only plain text but also binary content will be involved in the document, such as a UML diagram. And I've heard many people say that. The version control system is not the appropriate place for the binary files. I totally understand and agree with the issue. I asked several seasoned developers where the best place to store documents should be and the answer I got was "wiki". Wiki is good but I considered another potential issue. How can the source code which has been stored in a version control system connect to its related document in wiki? Let's say someone clones the repository of git or mercurial. How can he/she find the document easily? Or have I just missed something?

I know some wiki systems have the ability to integrate with source control systems. But my concern is not about the ability of integration. If you have cloned source code from a git repository and after a while you get on a train and want to continue to work offline on the train (which is a big feature of DVCS). Then you suddenly realize you don't have any access to document since you are working offline on the train. On the other hand, if the document was stored in git repository you would have access to the document with repository cloned.

Robert Harvey
  • 198,589
  • 55
  • 464
  • 673
Edison Chuang
  • 527
  • 1
  • 5
  • 12
  • 3
    FYI: Wiki is *not* an acronym, it's a Hawaiian word meaning "quick". – Jörg W Mittag May 02 '11 at 02:15
  • The fact that documentation involves binaries isn't really a good reason to avoid storing it in your version control system. VCSs can easily deal with binary files. And if you store it in your project's VCS, you have the advantage of being able to branch your documentation when you branch your project. – JW01 Jul 22 '13 at 18:04
  • As to working offline: The brute-force solution is to just download the pages you want using some offline-reader. More elegant is to somehow clone the whole wiki, if practical (e.g. copy the underlying database and have your own installation of the wiki). VCS-based wikis are an even more elegant solution. I often work offline, and usually just downloading the pages I need regularly is enough. – sleske Jul 22 '13 at 23:57

7 Answers7

17

Is WIKI really appropriate to store document for software development?

Instead of writing docs, pdfs and other kind of files, why don't you unleash the WIKI's full potential as a collaboration tool? You can write your documents there, attach your diagrams and even better: if you use Fitnesse, you can turn your wiki pages into really useful and living documentation, as they can become a executable specification.

Everybody knows that, well-documented software development leads to success

Watch out for this one. Documents WILL NOT LEAD TO SUCCESS, as they won't turn crap code into good one. But documents are a part of the way to the successfull software. But just a part and they wont replace good practices and good people.

Fernando
  • 1,025
  • 6
  • 6
8

Since multiple answers point to Trac as a suggestion I'd like to suggest a similar, but better in my opinion, alternative: Redmine.

Redmine is a project management solution, including Wiki, Document Repository and version control integration. It's also written in Ruby on Rails and way easier to extend and hack than Trac, in my experience.

More than everything it is really easy to use and it's easy to get the team using it.

Features:

  • Multiple projects support
  • Flexible role based access control
  • Flexible issue tracking system
  • Gantt chart and calendar
  • News, documents & files management
  • Feeds & email notifications
  • Per project wiki
  • Per project forums
  • Time tracking
  • Custom fields for issues, time-entries, projects and users
  • SCM integration (SVN, CVS, Git, Mercurial, Bazaar and Darcs)
  • Issue creation via email
  • Multiple LDAP authentication support
  • User self-registration support
  • Multilanguage support
  • Multiple databases support

For you offline needs, I don't like the idea of cluttering version control with design documents. I'm sure you have your reasons for asking this, but really how often you're offline and need access to design documents? Chances are this really a corner case.

Vitor Py
  • 4,838
  • 1
  • 27
  • 33
5

Some wikis (eg. Ikiwiki) have the ability to store their data in Git, as you mentioned. Given that, you can link the documentation as a Git submodule under your regular source repository.

With the above setup, pulling the source and updating the submodules would pull the latest copy of the documentation. Offline, you can edit each one at will. When you return to a network, both can be pushed back to whatever shared location you're using.

The awkward part of this is that whenever the documentation is updated (even through the Ikiwiki web interface), you would also need to update the corresponding submodule in the Git source repository. However, this could easily be automated.

Greg Hewgill
  • 10,181
  • 1
  • 46
  • 45
  • Interesting. Is there a difference between putting the document in git repository and storing the document via ikiwiki? – Edison Chuang May 01 '11 at 20:17
  • 1
    @Edison Chuang: No, there isn't. In fact, given a clone of an ikiwiki repository, you can edit the pages using the text editor of your choice (you don't have to use a crappy browser-based text entry box). You can even have different branches of the wiki, for keeping a snapshot of older documentation or whatever. – Greg Hewgill May 01 '11 at 21:50
  • It sounds like the document can be stored in version control system without any issue even though the binary files. Developer can just use tools like ikiwiki to convert wiki pages into HTML pages on demand. – Edison Chuang May 02 '11 at 01:16
  • +1 for the Ikiwiki wiki engine; the [Hatta wiki engine](http://hatta-wiki.org/) is a similar idea for Mercurial repositories. – David Cary Jul 06 '13 at 07:01
  • ISTR Fitnesse also stores its wiki pages as text files, so they too can be kept in your version control system if you wish. While its primary purposes is testing, there is no reason not to use it as a general-purpose wiki system for your documentation also. – Jules Jul 14 '16 at 09:18
3

It makes sense to store the documentation in the same repository as the source code. Sphinx seems like a good option to me.

Brecht Machiels
  • 248
  • 2
  • 7
2

Trac provides an interface to Subversion, an integrated Wiki and convenient reporting facilities. http://trac.edgewall.org/
But I don't know about your installed stack.

Chiron
  • 4,543
  • 3
  • 28
  • 37
0

I wouldn't try to conform to offline work. I would use the resource that make its easiest to work with for everyone. For example, if you are writing PHP code, I would suggest using inline documentation that can be generated by PHPDocumentor. It can be generated anywhere and there is a plugin for Trac. Then online or off, you have access to the documentation, fairly quickly too.

The key is about usability. If it is difficult to maintain, it will start to suffer. When it starts to suffer, documentation quality goes down. When that happens, people start to complain and then everything goes downhill.

Chuck Burgess
  • 386
  • 4
  • 7
-1

Using a wiki to store documentation make a lot of sense to me.

Veracity is an example of a DVCS that allow tighter integration of wiki content and source code.

Jace Browning
  • 2,173
  • 1
  • 15
  • 25