Export and Import a Confluence Space

This guide walks you through the process of exporting content from one version of Confluence (5.6.x) to another (6.6.x).

Exporting a space

1. Navigate to the space you wish to export.
2. Click on Space Tools > Content Tools.
3. In Space Tools page, click on Export tab.
4. In the Export Formats section, select XML and click on the Next >> button.
5. In the Export XMLOptions section, select Full Export (should default to this option).
6. Click the Export button to start the process.
7. Wait. Depending on how many documents you have in your space, this can take a few seconds to several minutes. Confluence will switch to a "In Progress" report page and periodically update the status of the download. Don't get discouraged if the original Time Remaining estimate lists some ridiculous number (it's just an estimate).
8. Once it completes the process, click the Download here link just below the completion bar. You should receive a zip file with all the contents and attachments.

Note: you can modify the contents of a space by modifying the entities.xml file found in the zip file. It would unwise to do this but if you need to programmatically change something throughout an entire space, you can do that.

Importing a space

1. Log into your target wiki instance with Confluence administration permission.
2. Under the cog, click on General configuration and then Backup & Restore. Even though this says it's a restore feature, it also acts as a space importer as well.
3. Under the Upload and restore a site/space backup, disable the Build Index checkbox. With this checkbox disabled, the upload will be faster. Otherwise, if you wish to build the index, you should do so after office hours depending on your server attributes.
4. Click on Choose File and navigate to where you downloaded your exported zip file and click on Open.
5. Click on Upload and Restore.
6. Confluence will take you to an import progress page that estimates the upload process. This may take a moment or two depending on the size of the space you are importing.
7. Once completed, you should check the newly imported space to confirm it's contents.

Write the Docs Newsletter – November 2017

Little late on catching up with my Write the Docs newsletter but November 2017 offered some good tips:

Worth it: images & screenshots

This month, we had a couple of conversations about images and screenshots that raised some interesting questions. When do we need to include images in our documentation? How many images is enough? How many is too many? Given how difficult they can be to maintain, are they even worth it?

Of course, our community of documentarians had a variety of good answers to share. For starters, there was a consensus that screenshots are inherently challenging. They take a significant time commitment to maintain, especially for a product with frequent UI changes. It was also pointed out that they are often overused and may not even be that useful to our readers. Diagrams, on the other hand, can be incredibly useful when designed well. Overall, the feeling was that using some screenshots and other images in your documentation is usually worth it, especially if you can commit some bandwidth to maintaining them.

Some other image tips that came up included:

• Crop your screenshots to highlight only the specific area of interface you're documenting.
• Keep all of your image files in a single, separate location. If possible, use version control.
• Develop – and stick to – a standard for producing screenshots: size, tool, resolution, file type, etc.
• Triage your updates. Prioritize functional UI changes over changes in button color, for example.

A {} by any other name

Sometimes, when scanning Slack, it's easy to spot which comments are going turn into newsletter fodder. Other times, a trivial comment will unexpectedly blow up. This month, what started as a quick 'hey, what's the name for this punctuation mark?' turned into a surprisingly in-depth and entertaining discourse.

For many of us, our primary use of {}, [], and () is in code. But what you might not know is that a) there is a dizzying array of names for these marks and b) when using them in prose, they have some interesting uses you might not be familiar with.

Just in our own Slack community, people said they refer to {} as squiggly brackets, braces, curly brackets, curly braces, and (totally seriously, I'm sure) curly wurly woos. If that's not enough, the wikipedia article on brackets is not only a hilariously deep rabbit hole, but also provides us with more names including: French brackets, definite brackets, swirly brackets, birdie brackets, Scottish brackets, squirrelly brackets, gullwings, seagulls, twirly brackets, Tuborg brackets (DK), accolades (NL), pointy brackets, third brackets, fancy brackets, and m braces.

As for their use in prose, as opposed to code, someone shared a Grammar Girl article, which digs into the various proper usages for () and []. (Curly wurly woos don't come up much in prose, so the post doesn't touch on them much.)

So remember, for the Write the Docs hivemind, there is no question too big, and no question too small.

It's your turn to ask the questions

We've all fretted over what we might be asked during an interview. But what about when it's our turn to ask questions? This month, a job-hunter sparked a great conversation about what to ask in an tech writing interview. We've written up a few highlights:

Show them you know your job. Asking specific questions about their expectations and processes can get you into the nitty-gritty, and give you a chance to show off your chops. This blog post has some good examples.

Don't be afraid to follow up. If something they say raises a concern – or just piques your curiosity – loop back to it when your turn for questions comes.

Ask what they think of your resume. Directly asking about your application materials gives the interviewer a chance to ask about your background, and you a chance to clarify or crow about your previous roles.

Have a couple backups. Some of your questions will be answered in the course of the interview, so come prepared with spares.

Clarify next steps. When the interview is wrapping up, make sure to ask when you can expect to hear from them. If they don't give you a firm date, tell them you'll follow up in a week.

The bottom line is to remember that you're asking questions to help you figure out whether the job is a good fit for you too.

To automate, or not to automate

One Slack contributor's triumphant story of automation success sparked a thoughtful series of posts about when and how to automate routine tasks – and when not to. We had a cautionary tale of an elaborate automated doc toolchain that couldn't be maintained after its creator left the company, nice distinctions between personal productivity hacks and automation for a larger group, and meditations on automation ROI. Here are some key takeaways:

• Automate all you like if it's just about your own work - whether it's email routing rules, keyboard shortcuts, or any other professional task for which you're solely responsible.
• Think more carefully about ROI and usability if you want to automate shared work. By all means automate routine and time-consuming tasks ("barnacle scraping" as one writer put it). But the cost:benefit ratio might not be worth it when it comes to one-off tasks. (This goes for personal automation too.)
• When considering an automation, consider not just the time and tedium saved, but also what it might take to make automation usable for more people. Make sure, too, that you're not threatening someone's job by taking away a manual process they're committed to or depend on.
• Remember that automation can help reduce errors, too.

Documentation Days

What is "Doc Day"?

Doc Day is the opportunity for a team to take a break from their day to day routine to write crucial or necessary documentation.

Abstract

"Efficiency is doing things right; effectiveness is doing the right things." - Peter Drucker

The purpose of Doc Day is to provide an opportunity for a team (or department) to take a break from their day to day routine and to either gather and organize documents, write new documentation, update or archive old documents, or to tackle long overdue documentation tasks.

The most common problem technical writers face is huge documentation backlogs and regular requests from both users and the teams to create or maintain documentation. While some roles of a technical writer is to become a subject matter expert, often time it is very difficult given time constraints, shifting schedule deadlines, and the consumer/tech writer ratio (at one point, I worked for a company that had a ratio of 2400 to 3).

While there are many methods to complete day to day documentation tasks, bigger projects and opportunities for the company to be more efficient can linger on and on and sometimes sit too long on the back-burner. Consider this scenario: John needs to write a document about a widget. John searches the company's internal documentation system for two looking information he needs. For the most part, he may find fragments here and there but not enough to go on. At this point, John resorts to information from his notes from previous team meetings (another hour spent researching). John knows that Adam (an engineer on the project) mentioned a point about the widget. John meets with Adam to gather information about the widget over the course of an hour only to discover that he wrote the tests for the widget and his information is too low level for the documentation. He informs John that Mary was the primary engineer assigned to develop the widget. Both John and Adam meet with Mary to get detailed information about how the widget was designed to work (or not). After a brief introduction to the task at hand, Mary invites yet another engineer (Po) to this meeting. Mary then explains to three different people the overview and main features with both Adam and Po asking questions and getting into minor debates every so often over the course of an hour. If Mary would have been given the time to write an overview document explaining the purpose of the widget, listed the features, and current bugs, she could have saved John five hours, Adam two hours, and Mary and Po one hour of searching, discussing, and meeting. Total time spent researching and sharing: 9 hours. Time Mary could have written the overview: 1 hour.

In this scenario, we see a rather bad use of time for everyone involved (though I'm not going to knock the value of personal interactions or connections). Engaging in a regularly scheduled document event, the engineers can spend an entire day writing new guides or refreshing documentation and possibly archive outdated documents that the team, their manager, and their consumers deem worthy of the Doc Day. The technical writer acts as a facilitator during this event providing support (both technical and writing related), hosts meetings prior to the event discussing the goals and assignments, writing and sharing templates with the team, and making oneself available throughout the event for answering any issues that arise. At the end of the day, the Doc Day concludes with a meeting where the participating members of the event meet, share their documents and snippets of their documents with the team, enjoy some refreshments, and (optional) receive an merit of honor (small gift or token of esteem). The participating members would each vote on the presentation, completeness of the documentation assigned, and any other criteria set by the event.

In my experience, everyone who ever participated in a Doc Day event, planned their time around the event to dedicate themselves solely to documentation, generally enjoyed the time while writing, looked forward to the next Doc Day event, and was thankful for everyone sharing their documentation effort at the end of the day. The team then reviewed the documents to learn more about what was written and applied any nuggets of knowledge to their own respective projects. The technical writer and the writer's manager is happy because some of their backlog and/or feature requests have been resolved.

How Does It Work?

The lead of a team designates a day (blessed from management) to work purely on documentation for one day. The team is given a notice of at least a week in advance so that they can submit topics to be documented.

Team members submit a list of items that can be documented in less than a day to their lead. The lead then goes through the list and makes the final list of topics to be written. Topics may be assigned to the submitted or to someone else who has deeper knowledge of the proposed topic. Topics should be able to be completed in less than one working day (approximately 7 man hours). Team members may write more than one topic if the topics can be completed by the end of the day.

Frequency

Ideally, Doc Days should occur every quarter but at the very least, once a year per team.

What Do We Write?

Anything that should be documented but currently isn't. Here are a few examples:

• A procedure that needs documentation
• Missing documentation from API modules
• Cross-training documents
• Instructional guides on various technologies
• Revising outdated documentation
• Anything that can be beneficial to the team, company-at-large, or our customers

The documentation can be either internal or externally facing.

Support

You friendly neighborhood tech writer is more than happy to help out with any writing issues you may encounter during your Doc Day assignment. Spell-check, grammar correction, technical issues with Confluence (wiki), and image capture/manipulation are a few services your tech writer is happy to assist you with. If English isn't your first language (or even if it is) and you're working on a document that will be public facing, please have someone review it before publishing it.

Doc Day Event

Prior to the Doc Day, the technical writer will set up a wiki page with all the assigned topics, writers, and links to the pages to be documented. This page will then be shared with the team the day before the Doc Day.

The day before the Doc Day, the team meets to go over their assignment topics and answer any and all questions about the Doc Day. The technical writer should be present to assist in answering any questions.

On the day of the event:

1. Team members start their day by reviewing their writing assignment(s).
2. Team members write their assigned topic(s).
3. Once a topic has been written, it can be submitted to the tech writer or team lead for review.
4. At the end of the day, the team meets for an hour to review the completed documents and vote on the best presentation and topic. The writer with the most votes wins a super cool prize.
   1. The doc review may or may not include snacks and liquid refreshments (of the adult beverage type).
   2. The prize can be anything: a badge of honor, gift card to Amazon (something of monetary value), or a trophy that is passed along from time to time.

Migrating Content to Another Confluence Server (and/or Upgrading Confluence)

Over the course of my career as a tech writer, I've also had the responsibility to maintain a Confluence server or two. In that time, I've performed several Confluence upgrades. Each upgrade has had unique challenges to migrate content from one server to another but they all have common steps that needs to be handled. Those steps include migrating plugins, user macros, and customizations, update and/or revise any automation scripts that depends on your Confluence server, content migration, and testing all the above.

In this month's post, I'm posting my list of common considerations for migrating Confluence to a new version. Below, you will find a checklist of steps that will ensure your migration goes smoothly. While there is no silver bullet in a complete migration process in the sense of which steps one should take first, in my experience, the order should look something like this:

1. Build a test server with the new version of Confluence
2. On a test server,
1. Install necessary plugins
2. Migrate user macros
3. Migrated customizations
4. Copy content
5. Duplicate and customize any scripts that depends on your Confluence server
3. Test everything!
1. Do the plugins work? If not, why not?
2. Do the user macros work?
3. Does the customizations act and function as they did before?
4. Does your scripts still work?
5. Is all your content present and accounted for (page content, attachments, links, features, etc.)?
4. Upgrade or update necessary plugins as needed
5. Update broken or malfunctioning user macros
6. Revise any customizations as needed
7. Test again with fresh eyes: Have someone outside your team do a test run on a space that you have copied over for testing your migration settings
8. Have a plan in place in case the switch over date encounters issues that prevents the migration from completing on time or failing all together
9. With testing and fixing nearly done, announce a switch over date that includes any downtime, list of deprecated features as well as new ones, and set your user's expectations accordingly

Plugin migration

1. Generate a list of plugins that needs to be installed in the new Confluence instance.
• Confirm usage of plugins. There's multiple ways of accomplishing this. One way is to use Confluence's own search engine to find any and all used macros of a plugin. First, generate a list of all the enabled macros that is packaged with your plugins. Second, in the search field (with the filters set to search all spaces), enter this: macroName: <macro>*. This will return a list of pages that use the plugin macro in question.
• Ensure deprecated plugins doesn't have any impact on our users. On your test server, you can check if an uninstalled plugin has any effect on your content. This can be accomplished in many ways such as brute forcing a review of every page that utilize your plugins or you can write scripts that checks the rendered HTML versions of your content for error messages.
• Generate a handful of pages that utilizes each active plugin in the current server. Once these pages/spaces have been migrated to the new server, you'll want to check these pages to ensure that the plugins are working properly. I found have these "uber plugin" pages rather useful to one spot to view the behavior of the plugins that will get migrated. One should note though, some plugins won't be compatible with others and some may slow the server down. Depending on how many plugins you have installed, you may want to split up your uber plugin page into one page for every 15-20 plugins installed.
2. Confirm that the current plugins are compatible with with the newer version of Confluence. This can be done by checking your admin section for any messages from the vendor about compatibility issues.
3. Install required plugins on the new server.
4. Report and track issues with the plugins.
5. Configure the plugins with the same settings as they were defined in the older server. This will ensure that your users have the same experience with the plugins as before the migration took place.
6. Clean up or archive pages that have uninstalled plugins. While this may be an optional step, if a page has become useless due to the unistalled plugin, there is a good chance that said page has outlived it's usefulness and can be archived.
7. Inform team of the migrated plugins were successful (with/without any notes about broken or archived pages, plugins removed, and their impact).

User macro migration

1. Generate a list of user macros:
• Confirm usage of macros. This can be accomplished by searching for macroName: <user macro>* in the search field.
• Ensure deprecated macros doesn't have any impact on our users. If they do, confirm that the page is still needed or not by your users. Chances are, they won't mind archiving this page.
• Generate a page that utilizes each required user macro. As noted before, you may need to split the user macros up between multiple pages.
2. Install required macros on test server.
3. Test user macros for compatibility issues.
4. Report, track, and fix issues for user macros.
5. Backup up revised macros (e.g. Github repositories, local backups, text files with the code, etc.).
6. Document changes to revised macros as necessary.
7. Inform team of the migrated user macros were successful (with/without any notes about broken or archived pages, user macros removed, and their impact).

Customizations to Confluence

Migrating customization between different versions of Confluence can be tricky. Between major versions, the framework and page layout changes which will adversely affect any customization you made using HTML, CSS, JavaScript, jQuery, frontend/backend libraries, and so on. While it may be tempting to go back to a "vanilla instance" of Confluence, if your users come to rely and use these customizations, you'll have to justify not migrating them.

Out of all the migration steps, this one is the trickiness due to their intertwined nature of your custom code and Confluence's. My advice here is to map what your customizations use to hook into Confluence. For example, if a customization relies on the page layout to always have a body element with a nested div element with the class of "content", make sure the newer version of Confluence has that same page layout. If it doesn't, map it out and adjust your customization accordingly.

Again, in my experience between major versions, I had to make adjustments or keep an eye out for custom features that involves the following web features:

• HTML: Atlassian tries to keep current with the latest HTML standards. You should too.
• CSS: Classes, ids, and element selection in the CSS files change as well. Check your custom CSS files for any changes you need to make as well.
• JavaScript: Keep your JavaScripts current and confirm that if the script hooks onto any element, that the element is still there as your script expects it to be.
• jQuery: Atlassian keeps current with industry standards on which version of jQuery it utilizes. If you scripts use jQuery, confirm that the newer version doesn't adversely affect your customizations.
• Libraries: Aside from jQuery, Confluence uses many other front-end libraries. You can include any library you like as well but make sure it still works with the new server.
• Confluence features: If you use a combination of native and 3rd party plugins, user macros, and/or customizations to achieve a non-vanilla feature, you'll need to ensure that this feature still works.

Content migration

With your plugins, user macros, and customizations migrated, you should start migrating production content.

1. Generate a list of spaces to migrate.  Confirm with our users that their team's spaces needs to be migrated. If not, archive the space using any method you deem worthy. Word of advice: it never fails that 1 in 20 users will ask you the whereabouts of a page that didn't get migrated 2-4 weeks afterward. I have been fortunate enough that we keep the old server around for just that purpose but if you find yourself in a different boat, I would recommend dumping an deprecated space to HTML documents, organization, and place them somewhere you can find them in the future. You may end up migrating the deprecated space anyway but mark it as "archived".
2. Lock a space prior to migration. This will ensure that no new pages will appear on the old server while migrating this space's content to the new server.
3. Migrate approved spaces. Track which spaces have been migrated.
4. Test migrated spaces: refer to your list of pages that have plugins and user macros that need to be checked. Do a spot check of a dozen or so random pages from the migrated space to ensure the content was properly migrated without any errors. Note: this could be automated using a combination of scripts to extract the content, parse the HTML documents looking for error messages, broken links, missing images, and report on which page and what error message(s) was found.
5. Report, track, and fix issues with migrated spaces.
6. Inform teams that their spaces have been migrated.
7. optional: Archive old spaces in the old or new server or in a non-Confluence repository.

Test scripts and external dependencies

1. Ensure that any script you utilize with Confluence works as expected. For example, if you have a plugin that generates a REST API for you to generate HTML docs for publication (pretty specific), then you should confirm that the REST URL and related scripts still generate content in a consistent form.
2. Review, test, and update your scripts accordingly.
3. Document any changes to your scripts. If the changes affects the public consumption of your content, inform your audience.
4. Back up your scripts. It is a good practice to have the old scripts archived.
5. Announce to your users, if they rely on the output of said scripts, that everything works as it should or if you've made any improvements.

There you have it. Hopefully, this guide will help alleviate any future issues with your next Confluence upgrade.

How to Deal With Bad Suggestions

In the article How to Deal With Bad Design Suggestions, I found that the suggestions listed therein also apply very well to how tech writers can handle bad documentation suggestions. Most of them are pretty straight forward if you've been around the block a few times but there's still a few nuggets in there worth mentioning.

Sustainable Documentation in Confluence

Maintaining documentation in Confluence can be challenging at times (especially if you work for a company that produces hundreds or thousands of pages a month). This post provides some tips on how provide for sustainable documentation in Confluence.

• Proper page names - this should go without saying. 
• Leaving comments when editing a page (even minor edits like fixing typos). This will help with reviewing the page (history) when an issue arises in the future 
• Linking is important (internally and to some extent externally). Confluence maintains links (intra and extra-space) automatically but doesn't valid or attempt to help the user when an external link is broken. If the external link is important, consider copying the content from the source and provide credit on the page. This wades into some grey areas that will need to be handled on a document-by-document basis (unless we have a company policy that provides guidelines as such). 
• Labeling - helps with search results and potential documentation groupings. Use simple concise terms, avoid plurals and verbs, and try to limit to no more than three or four terms. 
• Document hierarchies - Navigation my be king in documentation but it's not the "be-all end-all" solution. Keep the end user in mind. Topics must flow based on a simple logic or whatever logic your company deems necessary. 
• Minimal use of macros. Plugins come and go all the time (based on popularity and yearly budget). 
• Use page comments where necessary. If someone leaves a comment on a page that calls for action, do it, reply to the comment as such, and then remove the comments. It doesn't look good on us to leave years old comment on a page. Visitors will see the comment and may think the document is out of date. 
• Pictures are worth a thousand words or minus a thousand words if they are sorely out of date. Try to use generic images where possible in your general documentation. Product version-specific imagery should be generally avoided unless it is tied to a release. The same is true of videos. Also, Confluence isn't a media hosting service and file attachments are limited to 25mb (default). Videos attachments should avoided categorically. I have several stories (fun, sad, and problematic) about this topic. 
• On the topic if images, confirm that all images are properly attached to the target wiki page. While one can attach images from multiple sources (other wiki pages (complex topic), external sites, other servers, etc), you will run into publication issues if the images are not found within the Confluence server. 
• Using the search engine to suss out outliers and commonly searched terms. Try to do this on a quarterly basis to see where your users are going and look for potential gaps in your documentation. This creeps into using and reviewing analytic data to draw a bigger and clearly picture. 
• Try to find "Documentation Champions". DCs will be your ally in keeping the docs current and concise while notifying you of any weeds popping up their doc garden. Encourage them to contribute freely and review their work for minor issues (verbiage, typos, messaging, language issues, etc.). DCs will be your best resource to get other invested in the documentation when they feel welcomed, encouraged, and rewarded. 
• If some people on your team have not started using Confluence for documentation (a.k.a. "squeaky wheels"), engaged them. Ask why they haven't adopted Confluence. The reasons can be numerous but most likely, at least from my experiences, it because they don't want to "learn another program", "they're too busy to ...", or "I like my current workflow to document". Look for the pain points and point out that we are using Confluence as the main source of documentation. Does the squeaky wheel really want to be left behind? 
• Try to schedule regular doc reviews (annually would be nice). It's difficult to get the team engaged on this one but if one has the time to show the value of having fresh and current documentation, then the product manager should take this task up regularly. This will help prevent documentation overload. 
• Don't be afraid to archive documents in a separate non-searchable space. This will have to be negationed with you and your team. Confluence has the option to make a space searchable or not. All spaces are searchable by default but when a space is marked as non-searchable, the documents found within it will not show up in a search result unless requested in the search options. There are tools out that can automate this process but you'll have to see if we have the budget for that plugin. 
• Rely Confluence's version control for documents and attachments. When in doubt, check the page history and revert as necessary. 
• Use restrictions lightly. If you need to draft something that isn't ready for prime time, consider restricting the single page or parent page if the page count is under a dozen or so. If you have a need for restricting an entire space for whatever reason, do so but don't openly mention the restricted space in meetings. This will provide an air of mystery when there is none (hopefully). 
• Don't over-complicate permissions for individuals or groups. Keep it as simple as possible. You don't want to spend time managing permissions do you? 
• Refuse to provide people with PDFs of a document. Printing a page is rather wasteful if they have access to the wiki. While Confluence natively supports the option to export a document to PDF, don't go out of your way to advertise this feature. 
• If a page is out of date, look at who the original creator is and who last edited it. Contact those individuals and ask for clarity on the topic. Often time, these individuals (sometimes one in the same) will be happy to help you out.
• Templates are golden. If your users are afraid to create a new blank page, give them a template and ask them to simply fill in the blanks. This helps new Confluences get started with Confluence, gain confidence with Confluence, and helps you maintain order (somewhat) in how your content is formed.