search

SAP-archive / BUILD_User_Assistance

Here's the files for the GH-page for BUILD.
2 stars 2 forks source link

Known issues topic correction #37

Closed ghost closed 8 years ago

ghost commented 8 years ago

There's the Known Issues title, then a redundant sentence. Is this necessary? And if so, shouldn't there be a colon at the end of that sentence?

Is there a better way to display these so the issues are better to scan thru? Bullets, arrows, something distinct. image

ghost commented 8 years ago

Also, maybe group them under subheadings so you can browse which area of the app it affects?

ghost commented 8 years ago

Typo? Is something cut off? Purple square surrounds the previous day's

A purple square appears around the previous day's date when a calendar control is dragged onto the canvas.

Also maybe state it as Issue: xxx Solution: xxxx (or workaround, if any)

I051280 commented 8 years ago

DITA CMS User Guide 5.2.1 Short Descriptions [page 67] The short description is required in all topics. Contained in the element, it is a brief initial summary of the topic that has valuable uses for both readers and authors.

The short description is required in all topics. Contained in the element, it is a brief initial summary of the topic that has valuable uses for both readers and authors. The element is used as a topic's first text. As such it has several benefits as well as requirements. The element is output at the following locations: ● As a link preview The short description appears as a tooltip for links in published documents. This provides progressive disclosure of information from inside the documentation. ● As an abstract in a search engine's result The short description is included in search results. This provides progressive disclosure of information from outside the documentation. ● In the topic (as the first sentence or two) The short description is published with the topic. A good summary right up front makes it easy to scan the documentation and quickly know if you need to read the topic. Redundant, perhaps, but required.

ghost commented 8 years ago

@I051280 @brian-murray35

A few things.

The short description is required and should add value and not repeat the title of the topic. It is a link preview, and "brief initial summary of the topic that has valuable uses" and appears in the search so the user knows a bit about what's in the link, so they decide if they want to open it or not. A better short desc would be a good idea. As seen in these examples below.

image

image

As far as the link preview/tooltip in the published document, there aren't any in our help when I hover over the topic.

image image

A good example of a short desc is in Brian's topic here where it explains a bit more about the topic.

image