I usually try and catch up on various tech writing blogs over lunch, or sometime during the day. The first I read about the Atlassian doc sprint was on Sarah Maddox's website (http://ffeathers.wordpress.com/2012/07/10/yaayyy-a-confluence-doc-sprint-coming-soon)
I had never attended a doc sprint before, but was intrigued enough to read about the upcoming event.
Along with the immense challenge it presented personally, this was also a chance to work on a product and a team I’ve never worked on/with before.
What‘s a doc sprint?
A doc sprint is essentially a short gathering of people who work together to create or update an existing set of documentation, including the associated code.
The Atlassian Doc Sprint took place in their Sydney, Amsterdam and San Francisco offices, with a few other sprinters joining in remotely over 3 days (22/23/24 Aug).
What was the Aug 2012 doc sprint about?
The focus of the doc sprint was to create, edit/update developer documentation for Confluence.
Confluence is a collaboration tool that allows quick, online interaction between various business units. You can share, create, edit and store documents, project reports and everything in between centrally.
What I did during the doc sprint?
The tutorial I was assigned to was to update an existing tutorial "Adding your own Menu Items to Confluence".
I had never used Confluence before, so I knew this was going to be challenging. Furthermore, I also have had no experience in writing developer documentation, so this was going to be another first.
However, over the years, I’ve worked with a number of development teams and understand their perspective of looking at documentation.
Day 2 (23-Aug)
I joined the Atlassian team on Day 2 of the doc sprint. We had set up camp in the Kent St Atlassian offices. The view from level 15 was spectacular and there was ample chocolate on the table, fit for a king’s feast. The day started off with a sprint meeting and webinar, where we had a chance to speak to the San Fran team to find out how they fared on their Day 1. We were also given a quick demo on BitBucket (more on this later) and best practices on how to write tutorial docs.
One of my first tasks for the day was to read up on the installation notes to install Atlassian SDK and other components in order to be able to run Confluence on my machine. In order of installation, you need access to Java, Apache Maven, Eclipse, Atlassian SDK (and plenty of chocolate, if you have it!). Once I had these components installed, I could see Confluence in action, the way thousands of users worldwide do.
Essentially, what you do when you set up these components is to get the machine talking with Confluence and get enough control to change the way Confluence works.
Along the way, I kept notes of all these installations and indirectly made sure the Installation documentation was complete and accurate for someone new like me, who wants to install Confluence on their machine.
A word of caution though. The installation is a bit technical and it may be useful if you are familiar with a few system commands, technical terms and an idea of what is involved in an installation. To add to the fun, Confluence can be installed across any operating system that you use, be it Windows, Mac or Linux.
Once I had Confluence running, I was all set to run a test plug-in, ideal for a new starter to Confluence. The Atlassian documentation page describes plug-in as an add-on to the core Confluence code, which can extend the Confluence functionality. The test plug-in ran fine and I was ready to work on the tutorial assigned to me as part of the doc sprint.
Day 3 (24-Aug)
I returned to tackle the actual tutorial assigned to me on the last day of the doc sprint. The tutorial had existing documentation, so my task was run through the instructions and the included code, to make sure the documentation holds true for the current version of Confluence.
There were a few additional steps required before I could work on the tutorial though. I had to install 2 additional components Git and BitBucket, so that I could work on the code and store it on the Atlassian network. Git is an open source version control system and BitBucket is an Atlassian product which hosts the open source code.
Once I had Git and BitBucket sorted out, I was making the necessary edits to the developer documentation to match the current version of Confluence. I worked through the documentation and ran the code snippets without any issues. The draft of the developer documentation was reviewed for technical and grammatical accuracy. After getting an all-clear for the edits (and subsequent changes), I published my tutorial to the Confluence webpage.
Overall experience
My experience with the doc sprint was fantastic. The Atlassian offices are like a techie’s dream come true. Although I did not get a chance to meet everyone, the people I worked with on for the doc sprint were excellent. Not only did they make feel comfortable, they also took out time to help me troubleshoot and successfully run the plug-in code and update the documentation.
As with any Technical Writing project in the past, I discovered an eerily similar pattern where the tech writing transcends the mere documenting bit; it also involves testing, troubleshooting and even developing/programming (to a certain extent). More so, this being developer documentation as opposed to user documentation (something I am more used to); it did involve a lot of technical terms, concepts and playing around with the software.
Of course, it also helped that the theme for the doc sprint was chocolate. How else could we have managed to fire up those brain cells and stimulate them to create useful tutorial documentation? It also inspired me to submit the following entry in the Doc Sprint Haiku competition:
here have this, says Prof Lupin,
chocolate Potter
I suppose my only regret was that I was unable to join the doc sprint from Day 1, due to other commitments.
I greatly benefitted from working hands-on with creating a type of documentation, I haven't had the opportunity to work on in the past. With the focus of developer documentation being developers/programmers, I could identify the need to structure my documentation in terms of language, information included and style.
I eagerly look forward to the next doc sprint...
No comments:
Post a Comment