Writing Summary for your Artifact

Artifact Summary is a short description of the Knowledge Artifact containing the article’s topic and purpose. Luma Knowledge uses the Artifact Summary to generate Ontology for the artifact. It is essential that the Summary is well-formed and articulates the information in the Artifact. The NLP engine uses the text in the Summary field to generate Metadata.

Writing a Unique, Unambiguous Summary

Following are a few general rules of writing clear and effective Artifact Summary:

1. Start with a sentence describing the purpose of the article in terms the user is likely to understand. This should cover the issue, cause, task addressed, the approach taken, outcome, and/or result expected. This sentence should naturally establish the Topic but not repeat the title.
   
   Below are a few examples:
   “This article lists the  steps to set file permissions in Windows 10.”
   “This article is a tutorial on using pivot tables in Excel.”
   “This article explains who is eligible and how to apply for the Family Medical Leave Act (FMLA).”
   “This article is a troubleshooting guide for VPN access on  the West Campus.”
   
   

2. Optionally, follow with one or two sentences as needed to cover the remaining key subject(s) and uniquely qualify the artifact. This may be done by calling out qualifiers such as the cause, specific errors, situations, versions, models, environments, locations, or equipment. It ensures that the Artifact is identifiable and does not cause ambiguity with other Artifacts. These sentences primarily cover and qualify the artifact to assure uniqueness when similar articles exist.
   
   For example:
   “This article explains how to set Internet Explorer 11 settings when accessing  SAP v7 if  charts or diagrams are not displaying properly.”
   “The Family Medical Leave Act is only for US residents that have a medical situation in their atomic family.”
   “This troubleshooting guide should be used when experiencing "internet not available" errors at the Mt. Wilson Observatory.”

 Summary Guidelines

1. The summary should not be more than three sentences. Ideally, it should be less than 300 characters, maximum of 500 characters.

2. Write for the user audience. The summary provides the user a quick means to opt-in and read the article or ignore it.

3. Be as concise as possible. Error on the side of brevity as long as all the key subjects are stated and uniqueness is assured.

4. The summary is an inclusive statement, it should not mention what it does not cover. For example, do not say “This artifact is for iOS and not for Windows”. Windows should be covered in another article.

5. The Summary implicitly establishes the metadata or system’s understanding of the article. Use common, consistent vocabulary to describe the situation, and use the same across all other artifacts.

6. If the article addresses a specific issue, error, motivation, or cause,  state it. If it covers all situations, do not itemize them.  Use judgment here; if three recognizable things are covered, list them. Do not mention ten topics.

7. Do not use negation i.e. do not use “not” or negative contractions  such as “isn’t,” “wouldn’t,” “won’t,” “can’t,” etc.

8. Do not mention subjects and topics  that are  extraneous or incidental to the primary purpose

9. Use a similar expository writing  style across all corpus summaries

Summary Litmus test

• It is clear what this article serves.

• It is clear when or why someone would use it.

• It is clear who or what environment it’s for.

• The vocabulary is common and sticks to the subject at hand.

• If a similar artifact exists, it’s treated as a companion, and both are written in a similar manner but uniquely qualified as early as possible in the text.

• The summary assures uniqueness among other summaries in the corpus.