Documentation in a hostile environment
Hi LUV Main I have kept documentation in any formats from plain text, pod, apt, to docbook, tex and more. But I have never had to use Word (yes lucky me). I tend to have a Makefile, that does all the file converting necessary (e.g. turn my Mindmap into SVG into JPG, or similar). And of course, using Docbook (or APT to docbook) or TeX I can control all the formatting. Which leads me to my question. I am working now in an environment which is all word on dropbox. I am going crazy with formatting issues, corrupt documents (I have even installed MS Word on my Mac laptop to see if I can work around the problems by going to the source). A quick think suggests solutions for me is one of the following: * Modular word docs and use includes - not ideal still problems with formatting etc * Wiki (there is a Confluence system available for me to use) - but no offline editing, and terrible word/pdf output formatting * Build system (some text editable format I can use to generate the word docs). For the moment, the lucky thing is that I am working on these particular document mostly alone. That may not last and that is where the Wiki comes in, because at least the barrier to entry for the non-technical staff is low. Long story short, I am looking for examples, recommendations and personal experience. What would you use? Thanks Scott
Scott Penrose <scottp@dd.com.au> writes:
I am working now in an environment which is all word on dropbox [...] * Wiki (there is a Confluence system available for me to use) - but no offline editing, and terrible word/pdf output formatting
I would be promoting a VCS-backed wiki like ikiwiki or gitit. Your sales pitch would be something like - it's web based, and everyone loves that, right? - it's VCS backed without reminding users to turn on VCS inside word - it's on your own equipment, so <data sovereignty> FUD - power users can leverage git directly for deep magic - it can do OKish output to PDF &c - if a document really does need complicated formatting, you can always put just that one in dropbox. In my own office (which predominantly technical engineers, and 100% foss weenies) I rolled out gitit, because my SHOULDs included git and reST, and it looked to support reST better than ikiwiki. (It does, but it's a buggy in places.) I think that has worked out pretty well - the managers can cope with editing it as a wiki, and the engineers can edit it as reST text files in a git repo. I kinda hoped moinmoin would support git as a backend by now, but last I heard that was a SoC project that had been cancelled or something.
* Build system (some text editable format I can use to generate the word docs).
Problem with that is getting updates from other people back into it. Incidentally I received a docx yesterday and docx2text worked excellently without me needing to install 100MB of openoffice libraries (it's a shitty little perl script). If you need to continue interacting with .docx, you could at least set up something like svn, with tortoise for the normals, and tell it to unzip the .docx and normalize its XML as a pre-commit hook. That makes it diffable (to the extent that XML is diffable), at least. Since I mostly operate out of email, I also find it helpful to just ASCIIfy anything that comes in and send it back in the main text body. By the second round the other guy tends not to care anyway, because the whole discussion is happening over email, so it's just inline text instead of a docx attachment. I'd still use a VCS on my end, though, and then PDFize the final ratified version of the document.
On 14 November 2012 18:24, Trent W. Buck <trentbuck@gmail.com> wrote:
I would be promoting a VCS-backed wiki like ikiwiki or gitit. Your sales pitch would be something like
Or if you don't like static files and want something written in Ruby (not sure why these would be criteria actually), try Gollum: https://github.com/github/gollum This is the wiki used by github, although the version used by github appears to be an old version, and missing certain features (e.g. support for subdirectories). Gollum reads directly from git, and has a nice HTML based editor that divides the screen in two parts for real time preview. -- Brian May <brian@microcomaustralia.com.au>
Brian May writes:
https://github.com/github/gollum Gollum reads directly from git
So it can work in a bare repo? +1, that lack is annoying in gitit (as at 2010, at least).
On 15 November 2012 10:10, Trent W. Buck <trentbuck@gmail.com> wrote:
So it can work in a bare repo? +1, that lack is annoying in gitit (as at 2010, at least).
Seems to work fine. Does seem to require a ".git" extension on the directory though or it won't work. So "a" doesn't work, but "a.git" appears ok. -- Brian May <brian@microcomaustralia.com.au>
Brian May writes:
On 15 November 2012 10:10, Trent W. Buck wrote:
So it can work in a bare repo? +1, that lack is annoying in gitit (as at 2010, at least).
Seems to work fine.
Does seem to require a ".git" extension on the directory though or it won't work. So "a" doesn't work, but "a.git" appears ok.
That sounds like they're saying "if it has .git it's bare" when they should be saying "$GIT_DIR/config says it's bare, it's bare". Shrug; oh well.
Thanks to everyone for the feedback, some good ideas to run with there. Scott
Scott Penrose wrote:
..........snip
Which leads me to my question. I am working now in an environment which is all word on dropbox. I am going crazy with formatting issues, corrupt documents (I have even installed MS Word on my Mac laptop to see if I can work around the problems by going to the source).
I take it they are all a known version of MS-Word or some means exists to determine the version? regards Rohan McLeod
Scott Penrose <scottp@dd.com.au> wrote:
A quick think suggests solutions for me is one of the following: * Modular word docs and use includes - not ideal still problems with formatting etc * Wiki (there is a Confluence system available for me to use) - but no offline editing, and terrible word/pdf output formatting * Build system (some text editable format I can use to generate the word docs).
Would Pandoc help you with the second option? I don't know how good it is; I've only read the package description and have not installed, let alone run it.
Jason White <jason@jasonjgw.net> writes:
Scott Penrose <scottp@dd.com.au> wrote:
A quick think suggests solutions for me is one of the following: * Modular word docs and use includes - not ideal still problems with formatting etc * Wiki (there is a Confluence system available for me to use) - but no offline editing, and terrible word/pdf output formatting * Build system (some text editable format I can use to generate the word docs).
Would Pandoc help you with the second option?
gitit is built on top of pandoc, btw.
I don't know how good it is; I've only read the package description and have not installed, let alone run it.
It's... adequate. It does not implement reST fully and without bugs, so occasionally I try to do something (like insert a \n where the spec says I can) and it gets confused. Since markdown has no spec, it's markdown implementation is complete :-) Anyway, it's a reasonable choice for short / simple documents. For large stuff (not the case for OP) I would be looking at sphinx.
participants (5)
-
Brian May -
Jason White -
Rohan McLeod -
Scott Penrose -
trentbuck＠gmail.com