Moving forward with proposals for improving Documentation, here are a few more suggestions we (@vmassol, @paulinebessoles and myself) would like to share for discussion and feedback:
Proposal 17: Reference Pages and Tables
As a reminder, a Reference has the goal of presenting everything about a topic. The goal is to be extensive about a topic.
Reference pages must contain tables as a best practice because they present concise information and avoid verbosity. This way, there is also a visual separation from the other types of pages.
Pros:
Present information concisely
Avoid long paragraphs
Visual structure that’s easy to scan
Help distinguish reference pages from the other types
Cons:
Requires consistent formatting
Note: Diataxis emphasizes the importance of consistency in reference pages: "users should always find information in the same structure and format".
To improve accessibility and align with WCAG guidelines, it is important that on documentation pages, images and tables have appropriate descriptions.
Note: This applies to all non-text content/attachments, but so far, on documentation pages, tables and images are the most common.
Images:
The alt parameter should be used when inserting an image with the Image Macro, providing a meaningful description.
The caption parameter could also be used for adding brief visible content under the image, eventually specifying the version of the software the screenshot was taken in.
Tables and Figures:
They should be wrapped using the figure macro along with the figureCaption macro as in Figure Macro, also providing a meaningful caption.
Note: As a conclusion of the brainstorming, this rule is not enforced as a must, but as a should, meaning it’s highly recommended. This approach is chosen to avoid making contributions more difficult, as there are already many rules in place.
I think that reference pages would be really helpful for advanced users. And tables could make it a lot easier to find the information you’re looking for by just skimming the page. I’m in favor of this proposal.
I’m greatly in favor of anything that helps with accessibility, so a big on this one. I understand that you wouldn’t want to make contributions harder, so having alt, caption & figure as optional but still mentioned and encouraged in the Doc Guide, seems like an ok trade-off in my eyes.
Regarding this it would be good to have some templates for reference pages (and other type of documentation pages as well). Either a generic template or some domain specific templates (e.g. a template for a rendering macro reference page).
An API could be represented as a table for sure (one column being the method/functions and another one the description), but the issues are:
It’s very time-consuming vs just copy/pasting the interface
Copy/pasting the interface also copies the doc/javadoc and the most important is to have good doc/javadoc so it’s better to copy/paste than having to re-create the doc.
In addition, for APIs, we think we should add a “should” rule (ie a best practice) which is to add usage examples of APIs.
I agree it’s better to make an exception for references that are documenting APIs. There are already some rules for when inserting pieces of code (see Doc Guide-Macros). I updated the doc guide to mention the exception and linked to the section about how to use the {{code}} macro within the doc: Doc guide-Page title and content.
