git-svn based documentation workflow for mere mortals

Question

At my place of work we are currently looking for a documentation system for writing manuals and other customer and internal documentation. Its features should be:

• Small templating possibilities, since sometimes a customer name must be inserted somewhere, but the text stays the same.
• Reusability of text parts, since some parts might be skipped for some customer
• Revision control
• Easy review
• Easy to write for both developers and "mere mortals"

I proposed going with reST which would get converted to HTML and then, via PrinceXML, to PDF. Revisioning would be done in our SVN repository and we could thus re-use our existing Review Board installation, which is a nice bonus.

However, this system would not be very good for "normal" people since these are usually some interns who only know Word by name and can easily break styling (important for CI). Teaching them SVN is mostly out of question, reST might be as far as they get (cheat sheets will help a lot).

Sadly, the alternative is called Word and Sharepoint which is rather cumbersome for programmers and not very much reusable. Any form of CMS or Wiki feels a bit better than Word, but a question arises why to use Wiki when you can write same markup language in a simple text file.

So I want to adapt my proposed system to the needs of those mere mortals. This is what I've got so far:

1. SVN repository is cloned via git-svn, and switched to a working branch
2. A Samba server gets set up, which is showing git's working directory, with .git directory hidden
3. An inotify script is set up, commiting every save to the working branch
4. A review request at Review Board gets updated daily/hourly from the working branch
5. As soon as the documentation gets its "Ship it!", a manual script is run (by whomever) which would squash-merge the working branch to master and dcommit it. Old branch gets killed, new one opened, dito for review requests.

Now for the questions:

1. One big deficiency I see is the rebasing problem, since that'd have to happen automatically. How would you solve that?
2. Which other deficiencies do you see?
3. Can you propose some other workflow? Maybe some other tools can manage this better? There is practically no limitation on installation complexity, but usage must be as simple as it gets and the result as powerful as it gets.

Answer 1

A.f.a.i.k. your request for automatic rebasing is unfillable.

If you can get people to understand wiki syntax that's what I'd go for. Either MediaWiki and one of it's PDF output plugins (e.g. this one by PediaPress) or DokuWiki and DokuTeXit, though that seemed to have trouble with documents made from several wiki pages when I tried it a few weeks ago.

On a sidenote Prince is proprietary software. If you decide for reStructuredText to PDF conversion you can do that with Sphinx alternatively, widely used software libre. There also is rst2pdf but I have not tried that myself, yet.