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 about to start coding a documentation oriented wiki, as a pet project. The core features are:

  • Extremely easy grouping of documents per version
  • Markdown syntax (subset of)
  • Multiple authors & projects

I'm still undecided on storage options. The obvious approach would be a database. Since this is a pet project, I will probably go with a NoSQL solution, probably MongoDB. Most work related projects are based around MySQL, and I want to keep this fun, i.e. not do the same stuff I do at work all day.

The less obvious approach would be Mercurial, in similar fashion to git-wiki. Mercurial would offer obviously tighter integration with the code and I won't have to build versioning. I still need some sort of database, to store repository info and possibly other stuff, but Mercurial would be the main storage for texts.

I've compiled a small list of the major points for each approach:

Database

  • Can shape it as I want, without caring for Mercurial workflow.
  • Code integration could be as easy as putting a link to the repository (but nothing more).
  • Quite easy to switch databases at any point, if need be (abundance of native tools).
  • Natural choice (more people are used to it, not coupled to a vcs).

Mercurial

  • Versioning and diff by default.
  • Tight integration with code means lots of cool stuff are possible, like a code review plugin.
  • I'll have to write a wrapper, I'm not happy with every ready made library I've evaluated (not necessarily a bad thing).
  • Some sort of database still needed.
  • Several valid workflows, the one I choose for the tool might not be very compatible with those people will choose for their code.

I want to make this as small and fun as possible, and I am a little bit stuck on the two approaches. Thoughts? Is there something obvious I'm missing? If this is too fuzzy to decide, what should I better define before I choose?

share|improve this question

1 Answer 1

up vote 2 down vote accepted

If you're using Bitbucket with Mercurial, there's a built in wiki that uses Mercurial at a slightly different URL than your project, and it can be merged and branched separately, if you so choose. It uses a Wiki syntax that's not that different than any other Wiki system out there, and Wiki-based documentation is now fairly common at smaller companies that I've worked for.

I don't have the energy to build another wiki or documentation system, but if I were inclined to roll my own, I'd probably use some variation of this approach. It wouldn't be a hard sell with the documentation guy on our team, since most tech writers are now used to VCS in one form or another.

Documentation, by definition, is document-oriented, and a relational database is probably not the ideal fit for the problem; MongoDb is a reasonable alternative, but if you need versioning, diffs, and so on, you'll be reinventing solutions that are already well understood in version control systems. If you let the DVCS do the versioning for you, you'll be able to focus more on features that make your documentation-oriented Wiki, well, better for documentation.

Also, if you went the route of simply building the wiki features and not worrying about storage, since Mercurial gets you most of the way there, you can always refactor to support other storage mechanisms later, since you won't have tied your design to a specific database solution. If you start with the presumption of a database, you'll spend a lot of time engineering to support the interaction with the database, and it'll be hard to avoid the temptation to couple yourself to the features of the database system, so changing your mind later in that case may be harder.

share|improve this answer
    
There are some unique ideas for the project, but the main motivation is my long tradition of a fun pet project per year. I'm still brainstorming on some of the features, and I'll probably post a related question when I have a concrete list to get some specific pointers. I see the point for the mercurial approach, and it will probably help keep things simple. +1 –  Yannis Rizos Dec 28 '11 at 11:56
    
And the first draft of the idea was actually to use bitbucket itself as a storage, via its rest api. Several small complications there, but not completely out the window. –  Yannis Rizos Dec 28 '11 at 12:00

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.