: Re: Tools for multiple creators/writers documentation without clouds In many companies I've seen it that more than 1 person are writing at the same documentation (be it user manual or technical documentation)

@Hamaas631

Vote Up Vote Down

The main challenge of having multiple writers is dealing with conflicts -- either you have to lock files to prevent concurrent edits (as Word does), or you need a way to compare and merge changes. Locking files can be pretty limiting (especially as your group grows), but source-control systems give you the latter if you don't use a binary file format.

I wrote a lot elsewhere about the advantages of using source control for documentation. The key factors for you are the support for comparison (diff), merging, and branching. In my previous position I spent many years using Perforce (for source control) and XML (DocBook) source for documentation with a small documentation team. We had very few problems with conflicts -- only if two people made differently-drastic changes to the same section without talking with each other first. We learned to talk with each other first -- coordination for things like wholesale restructurings is still important, but we could just fix bugs and make minor updates without worrying. In my current position my team of about a dozen uses svn with HTML files; I haven't done an svn merge yet but I know it's possible. (I've been told it's not quite as nice as Perforce's, but it works.)

Comparison and merge tools depend on having meaningful source to compare, so that means you need to use some text source, not binary blobs. Regardless of what WYSIWYG editor you might use to edit your files, you want the stored format to be XML or HTML or LaTeX or some other text format.

As for generating PDF, there are lots of ways to attack this. I explained elsewhere how to generate PDF from DocBook source. Flare projects can be built to produce PDF (and HTML), which you can invoke from within the tool or externally. (We have a nightly build that builds from our Flare source in svn.) LaTeX's natural habitat is the command line and, again, it can produce PDF. (This is a placeholder for Scrivener, which I haven't used but I've heard great things about.)

Bottom line: use source control and use a comparison-friendly source format to allow multiple writers to work in the same doc set, and there are many ways to generate PDF depending on what you're doing.

(0)

Login to post a comment!