This is the accumulated knowledge we have on the issues with the wiki editor(s), converting from old to new, and the conventions we have for the content to keep things as consistent as possible. Much of the documentation may not entirely follow these conventions due to age, different authors, the previous lack of real advice, and because there are always situational exceptions.
The original content was built using what is termed the “legacy” or “old” editor that was used with Confluence Server. This editor was much more functional and useful than the “new” editor that the Cloud version favors, so the differences are quite significant. Unfortunately while the newly-formatted content is much less readable in a number of ways, Atlassian isn’t going to maintain the original editor and has already broken content in the old format once and we expect will do so again. So we have no choice but to convert the most important older pages, and new content really has to be built with the new editor, so the devil must be paid.
Chief differences and bugs/gaps:
Pages in the new format default to “narrow” mode and only render content in the “middle” of the window, wasting a ton of space. They have to be manually toggled to full width, easy to forget. This also affects tables, leading to…
Tables are much worse in the new editor and do not support responsive mode to set the column widths based on the content.
This is huge because of our extensive use of them in reference sections, and the responsive widths are the only thing keeping them readable, despite the occasional issue with cell wrapping. Creating tables (or cleaning up converted tables) requires very substantial, manual adjustment of column widths to prevent extra wrapping.
Links are moderately easier to edit in the new editor (subjectively perhaps) but have major limitations that impact us:
Links CANNOT be used together with monospaced content, such as XML element names or the like. We have been inconsistent with this convention but it’s used a lot for readability and to highlight syntax, and you cannot make that kind of text a link anymore.
Shortcut links are totally unsupported, which means our shorthand for linking to javadocs no longer works. Converted content will replace the shortcuts with the full URLs to our redirection scripts, but the new editor requires manually creating those links, which is obviously horrible.
The Code Snippet macro is quite a bit less functional than the old Code macro. The most significant issue is the lack of a “collapse” mode to limit clutter. This can be worked around with extra effort by wrapping the code snippet inside an Expand macro, but…
Nesting “rich” macros is impossible with the new editor, and this has been confirmed to be a permanent limitation. This makes a lot of very common idioms impossible to author, such as using the Expand/Code Snippet combination inside other macros such as the Tab add-on or inside warning boxes.
More will certainly emerge as we find new bugs and limitations.
As a general guide to converting pages from the old format, be aware of the differences noted above and the following tips.
Before converting a page, as much as possible needs to be cleaned up to make sure the conversion button is “green” and not “yellow”. Yellow indicates content problems that in some cases need to be fixed first. Usually this will be due to macro incompatibilities, such as the nesting issue noted above. The two most common issues will be the need to update to the non-deprecated Tab macro idiom (discussed below) and the need to eliminate Code macros nested inside warning/note/tip boxes.
In a few cases, it may not be possible to fix everything, but you should be aware that it may be impossible to fully edit converted content that’s not fully compatible so it’s usually best to leave such pages for further review.
Always Publish/Save the updated content before you convert. It is extremely easy to do a ton of cleanup on the page and then hit convert. You’ve just lost all of your cleanup and the converted page will include all of the old issues you tried to fix. Once you do it about twleve times, you’ll stop forgetting. Somewhere an evil imp inside Atlassian HQ is laughing at your pain. |
Make sure the table is full width (this goes hand in hand with making the pages full width).
Make sure that the tables do not contain any monospace/code formatting. This used to be a common convention for XML Attribute and Element names but the new editor does not allow monospace formatting to coexist with hyperlinks (the evil Atlassian imp cackles in glee). Equally the conversion is uneven; sometimes code comes out as monospace, but sometimes in a code macro. Finally monospace/code formatting looks particularly ugly inside a table.
After final cleanup, adjust the table column widths to be “reasonable” given a portrait view of the page. This is subjective, but it basically means mostly expanding the column to fit the content except for the Description columns. Also, beware of the right edge of the table being far off the page. You may need to zoom out to grab it and pull it back inside the page to avoid the table stretching way beyond the page view.
The Tab add-on was a mistake in hindsight because we didn’t know this Cloud migration was coming, and it’s much slower and less reliable in the Cloud (imp cackles again). With the lack of an obvious replacement approach right now, and a lot of content using it, there’s nothing for it but to hope it improves, so for the time being we just have to leave it.
Because of the nesting bug mentioned above, the original macros we used are deprecated and replaced by new versions that are somewhat easier to use in general but are a big pain to convert because all the content inside the old macro has to be moved outside it.
The starting point conceptually is:
TabGroup
Tab (Deprecated)
Content
Tab (Deprecated)
Content
The goal is:
TabGroup
Tab-In-Group
Content
Tab-In-Group
Content
So you start at the top of the tab group, add a tab-in-group per tab, and then cut-and-paste the content from inside the old macro. Don’t forget to make sure that the tab’s title corresponds. It is a bit tricky to cut and paste inside a tab (you tend to collect the containing macro) but adding some text before and after aid selection, especially so with tables. After a while muscle memory cuts in.
Given the time that tabs take to render, you may prefer to replace tabs by a series of expand markups. The title of the tab becomes the title of the tab and the contents, the contents.
With larger code snippets that are outside tabs, remember to add an Expand macro around the converted snippet macro to get back the collapsible feature. With tabs, this is impossible, so it’s a judgement call. In some cases, it might be possible to reorganize the content a bit to eliminate the tab, or it may be ok to leave the snippet expanded since it’s invisible unless the tab is selected.
In extreme cases, it is possible to work around the issue by creating a child page with the content and then including it in the tab, but this obviously gets ugly fast since editing the included content is very inconvenient.
As noted, any links using monospace text have to be fixed by removing the style and recreating the link.
Other links should generally convert ok, but checking them is usually a good idea. Be on the lookup for any remaining hardwired wiki.shibboleth.net links that need to be adjusted to become true wiki topic links.
Jira macros may need review, as they may not convert properly, and may be pointing to the old Jira instance as well.
Finally, beware of the (new in the last 10 days) pulldown giving you the choice of DisplatyUrl/DisplayAsLink/DisplayAsCard. This is can be a one way journey requiring a lot of Undo operations to get back content.
The title will come in as a 'Heading 3' which will then be rendered in the table of contents. You may want to make it 'Normal text` (ctrl-\) and then bold (ctrl-b)
The best convention is really “do what’s already done”, so copying existing pages with a similar layout is generally the best thing to do. The following is really just a reverse engineered summary of the general approach used.
Pages should be full width, as should tables in most cases, unless the table is short/small and looks better when narrower.
Pages should be primarily formatted for portrait-style browsing in order to ensure printed versions are reasonable.
Favor longer pages over many smaller ones. This is certainly subjective, but the documentation today takes that approach in order to increase locality of reference and make editing the “overall” topic easier by not having to jump around editing 5 or more pages. It makes printing out relatively complete docs on a topic easier for someone. Unless we reverse this approach, it’s been a common thread.
Incude a Table of Contents macro if the page is of reasonable size. Shorter pages can omit this.
Major headings are at H2 rather than H1.
Don’t repeat the name of the page topic at the beginning of the page itself.
The code snippet macro is rather less useful than the old code macro (though they both have their foibles). Shorter one-liner examples may be simpler to do using the monospace style alone rather than the macro. When doing longer examples with the code snippet macro, consider wrapping it with the Expand macro when possible. In conjunction with this, the title of the code snipper macro is not prominent like the title bar of the code macro was, and is hidden by the Expand macro, so the convention is to leave the converted format in place, with an H5 style used to document the “title” of the example or snippet.
Tables are fairly awful now, so avoiding them is usually advisable unless absolutely necessary, but they’re often necessary. Stick to non-monospace styles inside them, and make sure to adjust column widths to be reasonable because the editor will screw with them.
A typical approach to most topic areas is to include sections like Overview, Configuration or Basic Configuration, Advanced Configuration or Topics, Reference, and Examples.
The major topics should generally have a tabbed Reference section near the end with a complete reference to all of the relevant beans, properties, XML Attributes, child Elements, etc., as appropriate for the topic. A tab is recommended for each category of item, and tables are used for the information, until/unless we identify a better approach. When sets of objects are common across multiple topics, using a separate page and including it is recommended.
Older pages tend to use monospace styles for the left hand column to highlight the precise syntax used but this is no longer suggested and can’t be used when the names are links.
Many of the reference tables now combine the Name/Default columns in order to preserve column space when the defaults tend to be long.
When using tabs, make sure one (and only one) of the tabs is marked Active, and choose the tab most likely to be needed.
With shortcut links now broken, we have no choice but to spell out the links to the redirectors we use for these and just never break them.
Each script is used by linking to it and including the fully-qualified class name in the path, using either dots or slashes as separators.
http://shibboleth.net/cgi-bin/java-idp.cgi
http://shibboleth.net/cgi-bin/java-opensaml.cgi
http://shibboleth.net/cgi-bin/spring-extensions.cgi
http://shibboleth.net/cgi-bin/java-support.cgi
http://shibboleth.net/cgi-bin/java-mda.cgi
http://shibboleth.net/cgi-bin/guava.cgi
http://shibboleth.net/cgi-bin/jose.cgi
http://shibboleth.net/cgi-bin/spring.cgi
http://shibboleth.net/cgi-bin/java-ee.cgi
http://shibboleth.net/cgi-bin/java-jdk.cgi
The last one has the additional feature of a query string module parameter to point at the right module:
java.base
java.sql
java.xml
etc.
For example, linking to the DataSource class would be http://shibboleth.net/cgi-bin/java-jdk.cgi/javax.sql.DataSource?module=java.sql