Hacker News Reader

Comment by fian | Hacker News Reader

At work we are trialling Lyx + Subversion for collaborative creation of developer documentation. The stored data is in a text + markup format which allows for easy diffing. Lyx being a layer over Latex means we can easily transform into a wide variety of formats, but mostly we output to PDF and HTML. Subversion was chosen as we already had a server available and there isn't really the same need to branch/merge documents compared to code. Writing in Lyx took a little time to get used but I definitely feel more in control that when trying to wrangle complex docs in Word.

View on HN

I used to write my documents in Lyx too but spreading the tool amongst my colleagues involved a lot of evangelism. Markdown is a backend storage easier to adopt as developers are used to it (stackoverflow, github) but it produces output for the web : no pagination, header/footer, etc. Throw pandoc+tex template into the mix, and it starts to get really interesting : a quickly hacked markdown file transforms into nice pdf will all needed attributes. But why stop there? Now that you have a build process, move it to a server and add some hooks to injects traceability infos (author, last edit date, commit hash...) into the generated document, etc...

I went down this road, and it works surprisingly well. If you're trialling different solution for writing technical developer documentation, see a more precise description of the workflow that I pushed on my blog yesterday: http://kray.me/pro/doclegit-git-documentation-server/ (sorry for the copy quality, english not my first langage, corrections by mail are welcomed)

Interesting. When we set this up we looked at maybe adding an automated build (transform) step on commit via our CI (Jenkins) server.

While the software developers are comfortable learning and using Markdown or other markup syntaxes, I eventually would like to spread this approach to other technical people in the company. In previous attempts at teaching basic scripting (Awk, Ruby, Python) to engineers who are comfortable writing complex logic operations in Excel and who can dabble in VBA - I found a lot of resistance to the idea of learning a new syntax. So I expect the evangelism required to get these colleagues to write in Markdown will be greater than showing them Lyx, which at least looks like one of the editing modes in Word.

I thought the main technical hurdle (for not dev crowd) in my current workflow was git as there exist a lot of good Markdown editors on all platforms ;)

Reply on news.ycombinator.com