That Was The WeekAnother fairly quiet wiki week as I've been doing on a lot of writing for the latest release, as well as preparing for the next using the info coming from the Agile meetings.
We're still inching towards 4.2: I think that should be with us this coming week. To that end I've been studying all the changes Atlassian have made and have set up a page listing the updates and who should be interested in what changes. I'm not trying to dictate to our users who can use what - in fact everyone can see the full list, so can look at what they want. What I've done is to suggest which departments the changes affect the most, and the updates that will be of most interest too them. In other words, to supply a level of focus so that people can see what's most important to them, rather than wading through a list playing spot-the-benefit. I find that making a person's ability to use Confluence easier is the best way to get them to become more active within the wiki.While I was looking through the updates, I came across an enormous list of functions that are either already available in the current version, or will be with 4.2. Although I like to think of myself as a fairly experienced user, there's clearly a lot that I wasn't aware of. Which is great: now there's even more to play with. BTW, if you're reading this and you're my boss, I mean 'there's even more functionality that will help make me even more productive.'
This list is called the 'Full Features List 180 features.' And comes with this helpful advice: Get comfortable.Tip of the WeekA brief look at one of Confluence's many functions.
Name: Status Macro
Available from: Insert/Other Macros
Have you seen the coloured Status macro that you can use to label a page's content? They come in four colours (grey, red, yellow and green) so you can use them to show an easy-to-see view of, for example, a task's status. You can add your own custom caption too. So you could use red to mean 'on hold', yellow for 'on going' and green to mean 'finished'.You can also use them to help organise your tasks in your own way. For example, I might have finished a piece of writing that's been sent for review. To save me having to trawl all the words on a page looking for its current status, I could add a yellow label at the top of the page saying 'Sent for review'. Which means I'll be able to see the page's status almost as quickly as it can load.
I'm not sure if there's maximum number of characters you can use as I gave up counting at 100. That's not very practical as you can't use line breaks, which means it extends across the page without breaking.Which isn't very handy, but I suspect that Atlassian didn't design it with that in mind.
Cheers
That Was The WeekAt the moment I'm involved in a lot of writing, both for our new release, which is for clients, and the Sprint releases, which are still internal. So I'm doing a lot less wiki work (boo hoo). Or am I?
Well yes, there are (still) only so many hours in the day, but there's still plenty to do on both sides of my job. For example, we're still integrating the existing systems and users from the companies we recently aquired - which means investigating how we'll import data from another wiki and integrate Sharepoint, and discussing how all this is going to be achieved. Fortunately Confluence and Sharepoint can do this, though it's too big a topic to discuss here (and I've never done it) but you can find out everything you need to know here.Living In Exciting TimesI've been having some great conversations with new colleagues about using the wiki to bring all our disperate documentation together, how to manage corporate standards, agreeing what these are, what kinds of docs are we creating, and who is producing the docs in the first place.
Although there's a mountain to climb on this front - and just identifying those who might be involved is a challenge - what I know is that there are more than a few people who see the value of using Confluence to share and collaborate. So I'm expecting to get much busier on the documentation management front over the coming months.
Not only will the effort needed go on the docs themselves, a lot of energy will be spent on encouraging people to us the wiki. I won't pretend that take up isn't on the slow side at times, but once people begin to use it, once they see the advantages and benefits for themselves, then you find they (very quietly) become fans.
To this end, I've set up a global docs space which all those involved in this area will use as the hub of all our activities and communications. The plan is to draw people in by getting them to use it without making a song and dance about it. Apart from using the wiki to keep all our thinking in one place, I'm also going to use it to eliminate using email by making sure we all use the Share and @mentions functionality. Just imagine: more results and less emails - bliss!
So watch this space - and feel free to offer advice!Feet Up On The Desk TimeMy copy of Sarah Maddox's book Confluence, Tech Comm and Chocolate, finally arrived yesterday. I've only glanced at it but it's stuffed with useful info. And given Sarah's experience as both a programmer and tech author, you can't go wrong buying this book if you're interested in using wikis and documentation. I'm just wondering about how much of my working day I can justify spending reading it.Upgrade 4.2 Is Go!Yes, we're just about to upgrade to 4.2 and I'm dead excited about that! It's full of great new features and improvements which are not only going to make my life as a tech writer easier, but also a lot more fun. I can't wait to get my hands on the new Editor and to see how the What's Popular voting buttons will enable us to improve our user content.
Another benefit of upgrading is, as mentioned in last week's blog, that we'll be able to link JIRA and Confluence. For me, this means better access to the info that I need for my documentation, but it will also benefit development and testing, because they'll have also have easier access to the same info. This means, for the first time, that we're all able to use the same info in one easy-to-find place.
And just to make that even easier (have to stop using that word...) we'll all be able to use single sign-ons to access both systems. An additional bonus is the fact that we will be able to share the plugins that both JIRA and Confluence use between each other. This means you only have to have the plugin installed in one to be able to use it in the other - how neat is that?
Atlassian have also been busy working on the new Atlassian Marketplace, which, if I understand it properly, is pretty much a one-stop shop for all plugins. It should ensure that not only are plugins easy to find, but they will also be compatible with the latest version of Confluence. This means that when you upgrade in the future, you won't have to wait for the plugins you use to be upgraded too. Which cuts out a lot of hassle or not being able to use a plugin until it has also been upgraded and is compatible. And how neat is that?
Cheers.
That Was The Week That WasIf you've been following my progress using the page includes macro you'll be delighted to know that this is now live to clients and working very well.
As usual some of my week was spent looking after other user's and helping them with their problems. Not that there are many: yes things do go wrong from time to time but I can't fault Atlassian's responses and help when problems arrise. Most of the issues I deal with are quite simply and easily resolved, for example:- people forgetting their log on details
- people wanting help with a task, for example, moving page.
- people finding something that needs fixing but they are unsure how go go about it.
Of course I have to police any content changes in the client areas, but given that I can review all changes from within the email notifications I recieve, this doesn't take very long. That said, the more content we have and the more people we have editing and contributing it, the more notifications I recieve. This is something you have to keep on the ball with, and I review every notification as it arrives. Time consuming? Yes. Pain in the backside? At times, sure, but if you don't do it you run the risk of something being published that you just might wish hadn't. So far, and because clients and colleagues are professionals, this hasn't been an issue.
Confluence for Technical DocumentationThis week also featured a very informative one hour webinar entitled Confluence as a Platform for Tech
Docs which was presented by, among others, Sarah Maddox, one of Atassian's technical writers and author of Confluence, Tech Comm, Chocolate. I was fortunate with the timing of this as it started at 1700 CEST, which meant the Australia participants were up well past their bedtimes and those in the USA had an early start.
Shortcuts - The FilmI recently described using shortcuts to speed up actions and production, but I think this could benefit from seeing this in action.
Now thanks to the power of Jing, you can do that very thing by clicking here.
That Was The Week That WasMy main background task decided it no longer wanted to hide away in the shadows and instead burst out and took over my entire working week. I blame myself, but it was a long and repetitive task that I decided had to be finished asap - even if that meant hours and hours and hours of drudgery and repetition, replication and reiteration.
Still it could have been worse: I could have been using another tool: Confluence has a habit of making the dullest job rewarding.
Big Thanks!
I'd like to thank Andrew Frayling for his comment about how to make using shortcuts even faster and simpler in last week's blog. If you're a more advanced user, you'll find his blog fascinating and helpful.
Start Your Editor
I've talked a little in previous posts about writing and working within Confluence's editor, but I haven't really said much about the editing environment itself. So in this week's blog, I'll focus on some of it's functionality and the benefits it has for technical writers over more traditional tool such as MS Word.
The first has to be sheer ease of use, starting with opening the editor in the first place. If you're familiar with Confluence you'll know there's the big, hard-to-miss and very easy-to-click-on Edit button in the toolbar. Ignore it, it's not needed. You want to start
editing? Just press the 'E' key and hey presto, you're there.
I know, ridiculously simple and perhaps not worth all the song and a dance. But it is, because it demonstrates the detailed level of thinking Atlassian put in when they designed it. I.e., the user experience was upper most in their minds. This is very important because even now there are far too many software houses who forget to consider the user. I know this is true because I have to use such software on a daily basis. And I hate it.
So you've opened the editor and want to start writing, but you want to start by adding a heading on the page (as opposed to the page's heading). Which means formatting it. You could take the easy route and slide your mouse up to formatting the drop down list in the toolbar - but let's face it, your hands are already on the keyboard and your mouse is far, far away. In fact you know the whole operation of grabbing and using the mouse is very s l o w.
So why bother? Especially when you can create the heading you want just by typing it into the Editor? All you have to do is enter the heading code, press space and enter your title text. For example:
The heading's code uses the following elements:- h - always lower case.
- 1 - this is the heading level, so you could also use h2, h3 etc.
- a full stop - this has to be immediately after the number.
- a space - this effectively tells Confluence that what you've just entered is markup that needs to be converted.
The moment you press the space bar, the 'h1.' code disappears, and when you enter your heading, it uses the built-in CSS formating for Heading 1. All gloriously simple and very fast.
And there are tons of other labour-saving, speed-inducing devices in the editor. For example:
- for bullets, enter an asterisk at the start of the line and start typing.
- for a numbered list, enter '1' at the start of the line and start typing.
If you want to insert a non-numbered line into a numbered list, all you have to to is, at the end of a line of numbered text, press Shift+Return. You can then enter a normal line of text. However, when you press Return, the next line will be a numbered line that follows on from the last one. If you don't want that to happen, the keep using Shift+Return until you do.
Better, Faster, Stronger
There are many things you can do in the editor ranging from adding links to internal and external pages, using graphics, charts and videos. The possiblities are almost endless: I'll talk about more of
these in future blogs.
From Fact to Fiction
There now follows a shameless plug for my fiction writing...
I'm happy to tell you that my first novel, The Darkness Beneath, is now available as an eBook from Amazon (.com and .co.uk). It's a gothic tale of death and destruction in London's underground railway system.
Written with more than a passing nod towards the best of the Hammer horror and vampire films, you can download it in seconds for the very modest sum of $1.99 right now.
Cheers.
Another working week has flown by and sadly it was a forum-free week: my time was devoted to more urgent tasks, such as writing a How-To guide on setting up and using blogs.Not that I mind giving people more info on how to make better use of Confluence, but sometimes when you really want to crack on with a project, it becomes a project that is destined to slip out your grasp. Ultimately that won't happen with the forum, because I'm determined not to let go of it until it's working and being used by clients.Shortcuts and MacrosOne of the jobs I've been doing as a background task for the last few weeks has been to convert the contents of a spreadsheet into a series of wiki pages.This equates to seven columns of data for each row, and several hundred rows, all of which have to be split into separate pages. Each page contains one or more table depending on the type of info. And while all of these are separate pages (99 in total), they all have to be grouped into one page so that they can be searched en-masse and printed as a PDF.The process for doing this is easier than you think, thanks to some helpful built-in functionality, aka, macros.Although adding all the data from the spreadsheet is laborious and time-consuming, once you've added them, the process of grouping them onto one page is very easy. All you have to do is insert a macro into the page you've created to group the content on, choose the page you want to include, then saving the macro and the page. The whole process takes about a minute normally.To do this you can use another one of Confluence's brilliant shortcuts. In this case the shortcut is the left facing curly bracket. Another example of a shortcut is pressing the 'E' key to open the current page in edit mode. Brilliant! It's this sort of thing turns Confluence into the Swiss Army Knife of technical documentation.When you're in Edit mode, enter a '{' and the Macro suggestions window opens, see Figure 1. Next press the Up arrow key to select the Open Macro Browser option, and press Return.Now start typing the letters 'I, N, C' (you can use lower case, these are capitalised for clarity) in the search box. Bear in mind that you don't even have to click in the search box as the cursor's already there (yep, even more labour saved). When you do this, the number of macros displayed is reduced to only those whose name contains the letters you enter.The next step is to select the appropriate macro and enter the only parameter it needs, the page's name. Figure 2 shows the Include Page macro, while Figure 3 shows the parameter I've entered in the Page to include field. All you have to do now is press Insert to close the macro window, and then save the page.When you do this, the macro automatically gets the content of the parameter page and displays it on the page you've just saved. To add all the other pages you need using a seperate Include Page macro for each one.The contents of the group page are automatically refreshed whenever you open it, so if the content of the parameter page is edited, it is the new content that is displayed.But wait, I hear you say, what if I want to include a page that is in another space, is that possible? Providing you have permission to view that page, then yes it is possible - and not only that, Confluence makes it easy for you to do so. Spaced InWhen you start typing in the Page to include field, after you've entered two or more letters a list appears based on those letters, see Figure 4.The list contains pages with that name from all the spaces you can see. If you run the mouse over the options, the name of the space appears, see Figure 5.All you have to do is select the appropriate option, press Insert and save the page. The parameter you select has both the space's key and the page's name, for example - spacekey:pagename.I'm not sure if there's a limit on the amount of Include Page macros you can use on one page, but I've used 67 so far one page and it still works exactly as expected. In most cases you won't need to use so many (and if you do stand by for some te-di-um) and the benefits are well worth the effort. For a start you'll have all the info in one place, which makes it very easy to create a PDF (in two clicks) with all the content from all the included pages. For searching, you'll have all individual pages which can all appear as separate results. And you'll have one page with all the appropriate info which you can search using your browser's built in functionality.Details and BenefitsWhat I like about the ease of use we get with the shortcuts and macros is the attention to detail they show. Both demonstrate how much thought Atlassian put into their products, thought that all Confluence users can benefit from.
As this is my first blog about using Atlassian's Confluence wiki as a technical author, I think a short explantion is required.I've been working as a technical author for about 15 years, mainly in software but I've also worked in other areas such as hardware and OM document sets. My current role is with a British software house working in trading and risk management.Three years ago we started using a wiki for all our client documentation as well as our intranet. Last year we acquired two other companies, both of whom used Confluence. After comparing the two systems we were using, we decided to use Confluence throughout the entire organisation. That done, we migrated our original wiki along with the two other Confluence instances into one brand new one. A great deal of thanks for the success of this project have to go to Clearvision, an Atlassian partner, who organised and oversaw the whole operation.I firmly believe that Confluence is the way forward for technical documentation, and, having used wiki technology for three years now, I believe I have the experience and knowledge to back this up. I intend to do this in the coming months as I describe and share my experiences and insights gained.But First, This!Last Monday, the 12th March, I attended Atlassian's Unite conference in London. This not only gave me first hand access to various Atlassians, including Mike Cannon-Brookes (co-founder and CEO) but also to a huge number of people who are connected to Atlassian. They are connected because they are users like me, or are Atlassian partners. For example, Clearvision and Adaptavist.The morning kicked off with a talk by Mike Cannon-Brookes that covered everything from it being Atlassian's 10th birthday (almost) to sending out their very first invoice, to where their tools are now and where they are heading. After that we got further insights from other Atlassians into Confluence and JIRA, which in my eyes are the core Atlassian products. What I really enjoyed about all this was the refreshingly straightforward way the company presents itself. It might be that they put their best face forward, but there is no BS here - something a lot of other businesses would do well to emulate.Lunch looked excellent but I forsook the very long queue for it for a small salad. On the upside I managed to get myself a place at Mike's table (Atlassian had several tables manned by staff who were there to spit out advice and information between mouthfulls of lunch). Our conversation ranged from the enormous size of Australia, to the un-helpfullness of the weather, to promoting the use of Atlassian products to colleagues and senior management. It was refreshing to hear a CEO straight-talking instead of spinning and weaving.The afternoon continued with a couple more talks about JIRA and building the Atlassian community in the UK, featured demos from a variety of clients that covered how they used Atlassian's products in their production systems, and gave insights into how they promoted the use of the technology to staff. This is something I'm keen to know more about as part of my role is to be the wiki evangelist, and although most people see the benefits as soon as they start using the software, there are a few you have to use velvet thumbscrews on.Also, you might expect these talks to be primarily from software and technology businesses, which is true, but in fact manufacturing industries also use Atlassian's products. For example, we were treated to a lively talk from the world's second largest pump manufacturer in the shape of Ole Kristensen, the lead consultant at Grundfos.The day ended with everyone hot-footing it to a nearby bar for refreshments and even more conversation, free food and business card collecting. Which demonstrates another thing Atlassian is very good at: community building - which is almost the primary function of all their products. Obviously, on such an occasion, you can't talk to everybody, but you can target a few people and build more personal relationships with them. For instance, I built on my existing relationship with Clearvision and various members of Atlassian's support teams, and launched a new one with Adaptavist. This resulted in getting some very heplful insights into using their Community Bubbles plugin, (which we're using to build our client forum) plus the promise of some free support when I start setting it up.All in all it was an excellent day and money well spent: I went home full of useful information, fired up with the knowledge I'd gained, and very pleased with the opportunities for various collaborations that had arrisen during the day and evening.Now all I have to do is write up my nine pages of notes for my management report, fill in my expenses claim, and get the forum set up and working: life as a technical author will never be dull again.And Now For Something Completely DifferentAs of next week, my blog will focus more on how I use Confluence for technical writing and related matters. This means promoting the wiki and its usage to colleagues, technological issues, developing the wiki (structurally and functionally) support issues etc etc. Please feel free to comment and share your thoughts and ideas.
|
RSS Feed
