Tuesday, May 15, 2018

Some Confluence Resources

I do not long for the days when I used Confluence on a daily basis at Pearson. I am happy using RoboHelp at work as I work on Knowledge Management & Disaster Recovery documentation.
  1. https://www.google.com/search?q=confluence+tutorial+youtube
  2. https://wiki.nci.nih.gov/display/WikiTrainFAQsTips/Wiki+FAQs+and+Tips
  3. https://confluence.atlassian.com/doc/move-and-reorder-pages-146407727.html
  4. https://marketplace.atlassian.com/addons/app/confluence/top-rated?query=spreadsheet
  5. https://xmlpress.net/2017/02/28/confluence-tech-comm-chocolate-free-ebook/
  6. https://jira.atlassian.com/browse/CONFSERVER-14198
  7. https://www.atlassian.com/blog/archives/why-we-removed-wiki-markup-editor-in-confluence-4 
  8. https://www.k15t.com/software/scroll-translations
  9. https://confluence.atlassian.com/confeval/billing-and-licensing-evaluator-resources/customization-and-professional-services/do-i-get-access-to-the-source-code-if-yes-can-i-customize-the-code 

Hi Keith,

I haven't had to create a spreadsheet in Confluence, so can't answer that specific question.

But in terms of a bit of advice based on a couple years of experience maintaining content on a Confluence site with thousands of pages of content:

   1. If you have a single hierarchical arrangement in which you wish to
   present the topics you create, just organise them in the order you wish in
   the page tree, and you're good to go! If you wish to re-use a single topic
   in multiple different locations in the tree, a separate folder of
   topics-for-inclusion + the Include Page macro to include a shared topic in
   a particular page in the tree seems to do the trick quite nicely. It's not
   quite the same as a full-on authoring system with re-usable content blocks,
   but you can fake it acceptably using that technique.

   2. ** Consider your strategy for search early **. Search is one of the
   weak points of using Confluence as a documentation presentation platform.
   You can mitigate this by using naming conventions for topics that include
   terms users can put in searches, using labels, and even putting information
   in different spaces associated with different types of information since
   search can easily specify the space to search. Because clicking on a search
   result does not advance the displayed page to the location of the search
   string on the page (or highlight the search string on the page) when it is
   opened, we learned quickly that users prefer smaller topics if they plan to
   locate content using search more often than using a TOC or the page
   hierarchy -- because there's less of a document for them to page around
   looking for the content they require.

   3. ** Consider your strategy for versioning early **. You can do this by
   hand, using separate spaces for different versions, so that users can
   search for docs for different versions of a product by specifying the space
   associated with the desired product version -- this allows pages to have
   the same title across versions. Advantage: You can easily clone the space's
   content to a new space for a new version of the docs. Or you can do this by
   hand, with all documentation in the same space -- which requires you to put
   the version at the end of each title so that multiple versions of a
   document can exist in the same space. Advantage: It pleases an admin who
   sees a separate space for each version to be an excessive use of Confluence
   spaces, at the cost of making it a bit of a nuisance to create a new doc
   set for a new version of the product, for any pages that are not
   automatically generated an uploaded with a version-unique title. (No more
   will be said about that.) Or you can try out Scroll Versions and see if it
   meets your requirements.

   4. If you use Scroll Versions to manage across versions (it's not bad,
   depending on what you want to do, but it's not glitch-free either), beware
   that at least as of a year ago -- and probably still today -- you cannot
   post pages using the REST API if you want those pages to be managed by
   Scroll Versions.  We require this for some of our automated documentation
   production -- many of our collection TOCs and individual reference pages
   are generated using local table-driven tools and XSLs that create and post
   Confluence-internal-schema-compliant XML -- so Scroll Versions was out.

   5. Plug-ins are your friend. As Sharon Metzger pointed out, they are
   variable in quality, and some are very much worth the money.

   6. Beware moving and copying pages with embedded images that were first
   added by cut and paste. It seems to be better to explicitly insert images
   file-by-file if you ever plan to move pages around later. (This may only be
   an issue across spaces or may be an issue across permission boundaries.
   Once we determined explicit inserts fixed it, we just proceeded with that
   as process without investigating further.)

   7. Know that the Confluence Server editor is glitchy, but usually not
   fatally so. Confluence Cloud may have similar issues but I haven't put the
   hours into it that I've put into Server. If you are in the editor 6-8+
   hours a day and your topics tend to be on the longer, multi-page side,
   remember this: Control-Z will rescue you from all manner of scary ills!
   Occasionally -- 5-10 times a week for me -- you might be copying and
   pasting around a document, or attempting to apply a heading style, or doing
   something else other than simply typing in the editor, and find that your
   whole document suddenly renders in a particular style, the entire body of
   your document disappears, a cell in your table now contains what used to be
   the entire next row of the table, etc. When this happens, do not panic,
   just undo. Although Confluence sometimes gets the "do" part wrong, it
   RARELY gets the "undo" part wrong.

   8. If you want to buy a third-party theme setup plug-in, beware that
   they can interact poorly with other third-party plug-ins and Confluence
   itself. A theming package my employer uses causes me to constantly get
   "Cannot save page" messages from intermediate auto-saves during editing or
   for final updates -- even though Confluence does seem to save the page.
   Atlassian and the theme plug-in vendor are playing the "No, it's them!"
   game at each other; it's been an issue for most of a year.

   9. Sharepoint tends toward the over-designed end of things. Confluence
   tends toward the under-designed end. Neither are built to be full-featured
   content management systems, just easy-to-use web-publishing systems for the
   masses. The more you use Confluence, the more you will wish it can do, that
   it can't do, and the more you will understand that when they bolted a
   WYSIWYG editor on top of their product's existing non-WYSIWYG wiki editor,
   the end result works like a WYSIWYG editor bolted on after the fact. It is
   a relatively simplistic tool whose power derives from the ability to create
   plug-ins to do things that it, itself, cannot do. Welcome to the club.

   10. If you have a need to export content to Word docs, the Word export
   plug-in seems to produce acceptable output. It's not as well-formatted as a
   document created from scratch in Word would be, but it's OK.

Kind regards,

Helen.

No comments: