Atlassian no longer lets users comment on its documentation – good or bad news?

Last week, Atlassian sent out this message on Twitter:

This was a surprise, as Atlassian has been a strong advocate for having user comments appended to user documentation. Sarah Maddox, when she was working at Atlassian, posted the reasons why the company encouraged comments on her personal blog:

Continue reading “Atlassian no longer lets users comment on its documentation – good or bad news?”

Testing the Scaffolding (drop down list) plug-in for Confluence 4

One of the attractions of using Confluence to create reports is the ability to enter some of the content quickly by selecting items from drop down lists. This technique has been the key ways that one of our clients has been able to reduce the time they need to write reports from 1.5 days to 2.5 hours.

Although version 4 of Confluence has been out for a few months now, it’s only in the last couple of weeks that the plug-in for creating these drop down lists has been updated to be compatible with the new version.

So, does it work?

We’ve found the drop down lists worked in version 4 when we created new pages from scratch. However, the drop down lists didn’t work on reports originally created in Version 3 of Confluence. We did find out what was causing the problem, and the fix is to re-enter the drop down options in your lists. If you’re migrating content from version 3 to version 4, you’ll need to bear this in mind.

The drop down lists work well in Firefox and Chrome, but they looked slightly odd in Internet Explorer.

To use the drop down lists, you now click on a new button called “Edit Content” that’s at the top of the page – a more intuitive way than before.

Book review: Confluence, Tech Comm, Chocolate

I was sent a review copy of Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication, by  Sarah Maddox. It’s about using wiki technology for developing and publishing technical documentation, using the Confluence platform, the emerging trends in the creation of User Assistance and, in places, chocolate.

Confluence, Tech Comm, Chocolate

The book is aimed at three audiences:

  1. The person who isn’t sure what collaboration tools and wikis are, and is not yet fully convinced these are platforms they should use for producing and publishing technical documentation
  2. Someone who has used Confluence or another similar application, but sees themselves as a beginner
  3. Advanced users of Confluence.

The author manages to pull it off  – all three groups will find the book interesting and useful.

For the skeptics, Sarah raises and answers a great question:

Isn’t a wiki just a puddle of chaos?

The problem with the word “wiki” is everyone thinks of Wikipedia, with its complicated authoring environment and occasional errors. Sarah explains not all wikis are like Wikipedia, and how Atlassian, the makers of Confluence, struggles to describe the software (it currently says it “provides collaboration and wiki tools”). In fact, Confluence is a tool that can publish EPUB ebooks, PDFs, Word documents, HTML, DocBook files and, probably quite soon, DITA files. It has a rich text editor that looks like Word. It’s a wiki that doesn’t look like a wiki.

The book itself was written in Confluence. Comprising 477 pages, there’s a lot of “meat” in this book. We’d consider ourselves as knowing a lot about Confluence, having used it to build solutions for a number of clients, but there were many useful nuggets of new information.

Enthusiasm oozes through almost every page. That’s partly because Confluence is one of those tools that causes clients to get excited. They very quickly realise the potential outside of the original project. It’s also partly because the author is passionate about the subject.

Examples are built around a hero (heroine, actually) called Ganache, and this approach works well.

The book also looks at new trends in User Assistance – where technical documentation is going and how it will be created. A Cherryleaf article is mentioned in passing. It looks at working in an Agile software development environment, and how a collaborative authoring environment can help reduce the authoring bottleneck Agile can produce.

Sarah also highlights the weaknesses of authoring in this environment. There are issues around round tripping (and whether it’s needed or not), in particular.

Technical Writers will also have questions about translation and localisation of content, which is touched on only briefly. Publishing to .CHM files isn’t covered. However, there is a wiki that complements the book, so readers have the opportunity to raise these questions with the author (and discuss them with other readers) there.

If you’re interested in collaborative authoring, wikis, Confluence, chocolate, working in an Agile environment or where technical documentation is going, then it’s worth getting this book.