Working in a team can be a lovely experience or a total disaster. Most workplaces have dealt with these situations before, many are still emailing Word Documents between contributors and hoping to get feedback with track changes or comments which then need to get manually compiled. Using approaches like this can easily find maintaining a document almost unmanagable.

Writing documentation can be just as polarizing. It has been two years since OpenConcept released the Drupal Security Guide, a document which provides important security principles, best practices for basic security, and extra steps to be considered.
 
Originally, the document was created after the Canadian Government Security Agency website was compromised by a Pharma Hack. We were able to help them quickly build a new server, clean up their existing site and provide documentation on how to keep it secure. We weren’t able to find anything on the market that we could just give to them, so we ended up writing a security document of our own. Unfortunately, security on the Internet is being challenged daily, so this document would need to be updated often, with input from multiple sources.
 
We started off writing this document in Google Docs. This would allow us to share the information easily and also invite people to view it while it is still in draft. We were able to share the document with the Drupal community and get feedback from a lot of key security experts.

Although web security is a highly technical, we realized that many of the problems were based on management's level of awareness. We needed to write a document that had enough technical information to be useful for implementors but with enough strategic guidelines that managers could understand the context better.
 
Usingn Google Docs went fairly well, although we encountered an issue when trying to export information into a PDF format. Google converted all of the links to Google redirects so that they can keep track of who is clicking on what within the document. For a security document, this was just unacceptable. Exposing this information about user behavior to Google (or any other 3rd party) should be unacceptabe for most organizations. Fortunately, after we discovered this problem, we were able to export the Google Doc to OpenOffice and retain the original URLs.
 
From there we were able to do some extra formatting and export it as a PDF. Sadly, the conversion process wasn’t very smooth and we had to spend a lot of time cleaning up the document before producing a PDF. So while Google Docs was a great resource for writing the document, the actual execution left a bit to be desired. Google also isn't an option for all users. Some people and organizations have legitimate concerns about what they share with Google.
 
We also really didn’t like the PDF file format. OpenConcept has done a great deal to make Drupal 7 and 8 accessible to everyone. We’ve made a big commitment to accessibility, and yet when producing this document, we were stuck with the same terrible accessibility problems that most PDFs have. We later found an ePub solution with Sphinx, which you can read more about here. (3)
 
This ePub solution allowed content creators to on the content and structure and not be distracted by the formatting. Changes are easily tracked in a version control tool like Git and using tools like GitHub it is quite simple for technical people to contribute. This was a much better approach than Google Docs and was much more convertible for accessibility purposes.

Unfortunately, it still isn't as easy to get started as it is with Google Docs, but this should change. We are seeing government departments in the USA & UK using Github to provide version control (transparency), feedback (forums), and forums (pull requests) open to anyone on the Internet. More documentation will be written using open, web-first tools like this.

Overall, the experience taught us a lot about collaborative documentation and just shows the options available for anyone willing to collaborate on just about anything.
 
To see the results of this process, you can take a look at our security guide. (1) If you have a collaborative documentation story of your own, feel free to leave it in the comment section below.