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) for a computer application.
What I have seen in usage was mostly svn in combination with windows word. This combination never worked out quite well and was quite a hindrance as far as I've seen. Other solutions that functioned better for multiple users used clouds to store the data (example google docs) but that could be a problem with company policies in regards to storing important data externally.
So my question would is, if there are any tools that fullfill the following requirements:
- PDF files are generateable
- Does not use an external cloud for storage but instead can either be used locally OR the company using it can setup their own cloud for it
- There is no large overhead for having multiple users work on the same part of the documentation at the same time (or on different parts in the same file)
This post was sourced from https://writers.stackexchange.com/q/12995. It is licensed under CC BY-SA 3.0.
2 answers
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 comment threads
I have used source control in documentation for several reasons besides multiple writers working on the same file. Some other uses are:
- Tracking and communicating changes
- Deploying documentation to a web site
- Integrating documentation with software builds. For example, I worked in a doc/software system that facilitated linking javadoc to other documentation.
- Documentation review. Depending on the format of your documentation, you can use the same review tools that software engineers use for reviewing their code. For example, HTML documentation is relatively easy to review this way.
I also think that you should strive to divide up documentation tasks so that writers work on their own set of files whenever possible. I can think of a huge number of reasons that this approach is preferable.
Having said all this, here are my specific answers to the OP's question:
You can generate PDF from HTML or XML, given the right tools. PDF is so popular that many tools support it out of the box. Because PDF is Adobe, the best PDF generation support is from FrameMaker, alas.
If you want source control without a cloud server, you should look at Git, which is an open-source distributed system. Technically speaking, Git doesn't have a "central" repository. Instead, everybody that's interested in a set of software , documentation, and so forth gets their own copy, which is called a repository. All repositories are created equal, and each one can be branched and merged at will. Most of Git's software handles merging and conflict resolution.
I can't answer for the overhead of the tools for generating PDF, but the overhead for Git depends on the number of files and the type of each file in each repository. Internally, Git tracks changes to text files rather than the entire file itself, but Git can't do this for binary files (such as .fm or .doc).
This post was sourced from https://writers.stackexchange.com/a/13019. It is licensed under CC BY-SA 3.0.
0 comment threads
0 comment threads