...
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.
Style Conventions
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.
Javadoc Links
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