Tag Archives: Documentation Tools

Five Reasons I’m Falling Out with Confluence 

After a tumultuous and slightly short-lived affair with Sharepoint, I was introduced to Confluence and I was quickly won over by its simplistic UI and text editor. However, three years later I’m starting to feel disillusioned and frustrated with it. Here are some of the reasons why:

1. Bloat

Confluence has become bloated. I’m not sure if it’s a result of popularity or customers’ demands for new features but the feature set has been bloated while the basic functionality is neglected. It’s like a pet dog that has become fat and lazy from too many treats.

160402182953-tease-overweight-dog-update-irpt-full-169
Confluence now and Confluence before …

2. Bugs

Any frequent user of Confluence will be aware of the numerous bugs that seem to go unfixed for long periods of time. We encountered  a bug last week where images were breaking when copying a page (we later discovered this was caused by the image name having a colon).

Another common bug, which has caused me grief in the past, relates to being unable to export pages as PDFs for various reasons. This case, first reported in 2014, is still affecting customers two years later: https://jira.atlassian.com/browse/CONF-34275

2017-03-19 12_43_51-Clipboard
An example of customer frustration…

3. Plugins

To do anything useful or practical with the vanilla version of Confluence you need to install expensive plugins. Want to use versioning? You need buy a plugin. Want to translate your content? You need to buy a plugin.

2017-03-19 12_59_12-Films & TV
Even “Atlassian Verified” plugins don’t seem very reliable and are often costly.

Apart from the additional costs, my main issue with this is only a handful of plugins are built and maintained by Atlassian so you either have to take the risk of using a free plugin that will break in the future or you have rely on a third party developer to continue supporting it to ensure it works with newer versions of Confluence.

4. Basic Missing Features

The basic text editor in Confluence, the thing at the heart of the software, is still pretty poor and even things like basic formatting are a chore unless you manipulate the CSS.

2017-03-19 13_20_33
It amazes me Confluence still doesn’t offer other fonts or the option to change the font size.

Off the top of my head, the things that annoy me include: you can’t insert certain macros directly after another macro or a table because they will break or it will mess up your formatting, you can’t create a table without borders (unless you have Source Editor), you can’t choose different fonts or font sizes (unless you import them in the CSS), you can’t change the background colour, you can’t justify your text and you can’t remove historical attachments that have been uploaded to a page in the past. These are all things I’ve just accepted as Confluence-isms, things you just have to accept that Atlassian aren’t going to fix any time soon.

5. Cost

Despite all these things, Confluence is not cheap. If you’re a company with 100 or more employees, the Cloud version will set you back 3,000 dollars (£2,419) each year:

2017-03-19 13_24_50-New notification
Ouch: Confluence is not cheap!

On reflection, it’s pretty scandalous how much they are charging when so many bugs still exist, basic text editing functions are missing and most companies will need to install and pay for further plugins to get it to meet their requirements. Unfortunately, until someone comes up with a decent alternative I don’t see things changing.

Have you found a decent alternative that can be used for wiki content or software documentation/online help? If so, please let me know!

How to become a Technical Writer

If you’re an analytical journalist who is looking for a change, a budding writer with an interest in technology or an experienced programmer who is secretly an aspiring wordsmith, then technical writing might just be the answer for you.

What is a Technical Writer?

Technical writers or authors help to communicate technical information and instructions for products, such as software and hardware, in a way that is easy to understand. This can include writing user manuals, online help, release notes, integration guides, fact-sheets, wikis and APIs among others. Other methods of communicating information include producing video tutorials, graphics and illustrations. If you’ve ever read the mini instruction manual that came with your smartphone or clicked the ‘?’ icon or ‘Help’ button while using a piece of software then the content was probably written by a technical writer.

The role is sometimes given other names such as technical communicator, documenter, information designer and content strategist. Occasionally the content is written by developers or business analysts.

Moving from Journalism into Technical Writing

After nearly six years of writing for local newspapers and witnessing more and more job cuts as readership declined, I decided to jump ship and try something new.

Side profile of a journalist typing on a typewriter

My lifesaver came in the form of technical writing, and while it might not be for everybody, I knew straight away that it was the right move for me. Skills I had used for years such as interviewing, writing shorthand and producing accurate copy quickly proved to be very much transferable but instead of interviewing local politicians and press officers to write news stories, I was speaking with developers and testers to produce release notes and user instructions. Similarly, my multimedia skills and experience with Photoshop and video editing came in handy for creating graphics and video tutorials. It certainly helped that I’d always been interested in computers and had worked on blogs (so had some basic knowledge of HTML etc) but I found most aspects of the job just suited my existing skill set.

What Background should a Technical Writer have?

While I have encountered that some companies who would rather hire technical writers with a coding or technical background, I don’t think that should be a stumbling block if you’re interested in pursuing a career in technical writing. I have met technical writers who have previously worked in customer support, higher education and even photography. Although I have personally found my journalistic skills incredibly useful, I think as long as you are a good writer, are able to think analytically and are happy to constantly learn new things then a career in technical writing could be for you.

The sections below will provide tips and advice that will help you if you are considering pursuing a career in technical writing:

1. Qualifications

Some employers will look for a degree in computer science or similar but requirements can depend on the subject matter of what is being documented. Degrees in science, engineering and English are all suitable.

While there aren’t actually too many universities which offer accredited technical writing courses, it certainly wouldn’t hurt your CV to have some kind of formal training in technical communication. The University of Limerick offers a graduate certificate in technical communication (distance learning), while  other universities such Imperial College and Norwich offer more specific or specialists courses such as science communication and communication design.

Introductory and more advanced courses with accreditation by the Institute of Scientific and Technical Communicators (ISTC) are offered by Cherryleaf, Armada and ESTON.

2. Commonly Used Tools

Another key thing that most employers look for is experience with the required publishing tools that their documentation team use or have used. The table below lists many of the products and tools that are commonly used by technical writers, although there are many others:

word_2013  Microsoft Word  Word processing tool.
sharepoint2013  Microsoft SharePoint  Documentation management tool.
default-space-logo-256  Atlassian Confluence  Documentation management/ team collaboration.
icon-flareLargeBgColor  Madcap Flare Help authoring tool.
FM-icon  Adobe FrameMaker  Document processing tool.
2016-05-18 12_27_22-Films & TV  Adobe RoboHelp  Help authoring tool.
Adobe_Acrobat_DC_Icon  Adobe Acrobat  PDF reading and editing tool.
Notepad  Windows Notepad  Plain text editing tool.
notepadplusplus.6.9.1  Notepad + +  Text and source code editor for Windows.
Adobe_Photoshop_CS6_icon.svg  Adobe Photoshop  Image and photo editing software
Visio-icon  Microsoft Visio  Diagram and flow chart creation tool.
visual_studio_2012___windows_startscreen_icon_by_revisionzero-d5qnp17  Microsoft Visual Studio  Integrated development environment.
greenshot_0a  Greenshot  Screenshot capture and editing tool.
img_snagit-icon  Snagit (TechSmith)  Screenshot capture and editing tool.
icon128-2x  Camtasia (TechSmith)  Screen recording and video editing tool.
Adobe_Illustrator_Icon_CS6  Adobe Illustrator  Vector graphics creation tool.

If you haven’t used any of the software listed above, it is possible to download 30-day trials of some of these (Adobe Software especially) and either play around with them or watch some tutorial videos online and read online help to learn how they work. Many open source tools such as Greenshot and ScreenToGif, which can be used to create .gif files from screen recordings, are completely free to download and use.

Another useful tool to use when starting out as a technical writer is to buy a copy of the Microsoft Manual of Style. This is a great everyday generic style guide that can be used as a guideline for your own technical writing or as a template when creating a style guide for an employer.

3. Coding Skills

While it is not essential, as I said before, having some basic coding knowledge would be extremely beneficial if you are serious about becoming a technical writer. Some people recommend learning the basics of HTML, CSS and some XML at the very least.

coding-future

There are some excellent online resources where you can learn different coding languages. These include:

Codecademyhttps://www.codecademy.com/

Khan Academy – https://www.khanacademy.org/computing/computer-programming

Code School – https://www.codeschool.com/

W3Schools – http://www.w3schools.com/

There are more out there and there are also plenty of forums and tutorial videos available which should give you the basics. Starting a blog or creating a website online is also another great way to learn and develop your HTML skills at the very least.

4. Build a Portfolio

It’s difficult to build a portfolio when you are just starting out and do not have work experience but one option is to go to freelancing websites and find some documentation jobs, write submissions and use them for your portfolio, whether they get accepted or not. Another option is to find an open-source collaborative project such as Mozilla Firefox (and Thunderbird) where the documentation is written by volunteers. Click here for more information.

If all else fails then simply produce dummy documentation samples such as user guides or fact-sheets for existing products. It would be good to have half a dozen or so of different document types, preferably both user-facing and back-end, to really showcase your work.

5. Networking

Once you have the qualifications, knowledge of the tools and a small portfolio, it is important to network and develop contacts in the industry. It is a good idea to look up and contact firms which have existing documentation teams who might need a junior technical writer in the future.

networking

Alternatively, write a list of companies you’d like to work for and either check their career sections or email them speculatively offering your services. Other ways to build your reputation and network is to send your CV out to recruitment agencies who specialise in tech jobs, add contacts on Linkedin and attend technology job fairs in your local area to get your name out there.

Finally, good luck with your search!

Was this post helpful? Let me know if the comment section below.