[LUDOC-530] Various problems in Lustre online manual identified with an LLM

• Type: Improvement
• Resolution: Unresolved
• Priority: Minor
• Severity: 3
• Assignee: Ellis Wilson
• Reporter: Oleg Drokin

Description

Since we have a DGX sitting mostly unused (gpu-wise), I thought it would be an interesting idea to run it on various documentation we have to highlight problems. This resulted in various useful actionable data and Andreas suggested to do the same on the Lustre manual.

This also seems to have returned useful data, I am going to post the structured results here hoping somebody could take a look and push patches as needed.

Do not take the suggestions as gospel, but in general it highlights somewhat problematic areas and even if you use a different way to fix it - that's still beneficial. In particular suggestions like "use file system or filesystem consistently" are good, but unlike what the model proposes, we actually want to use filesystem as a single word.

The results from my manpage runs suffered from some hallucinations including some not really there spelling mistakes, so don't be surprised if you encounter something like this, but this is a much larger model result, so should be better at not doing this. In fact I did some spotchecking and it looks like all spelling errors below for the most part are not there, may be the prompt needs to be improved to say that it's ok for there not to be any spelling errors?

This is the prompt I used (model llama 3.1 405b quantified to 4 bits from 16 so it actually fits):

prompt = """You are an expert proofreader and your job is to review Lustre filesystem documentation.
Read the below section in XML format for spelling and grammar errors, inconsistencies and poor wording:
```
%s
```Proofread the above document and provide your feedback.
Be specific and short, recommend suggested fixes for misspellings and grammar errors.
Limit every suggestion to 50 words or less.
Explain inconsistencies.
Respond using JSON like this:
 {"spelling":[{"original":..., "fix":...}],"grammar":[{"original":...,"fix":...}],"inconsistency":[{"original":...,"explanation":...}],"wording":[{"original":...,"suggestion":...}]}
"""

As you can see, the results are JSON split into different categories, hopefully even if you don't know what json is too deeply, the data is useful.

Comments

[Oleg Drokin]

SettingUpLustreSystem.xml

 {
  "spelling": [],
  "grammar": [
    {
      "original": "The size of the MDT backing file system depends on the number of inodes needed in the total Lustre file system, while the aggregate OST space depends on the total amount of data stored on the file system.",
      "fix": "The size of the MDT backing file system depends on the number of inodes needed for the total Lustre file system, whereas the aggregate OST space depends on the total amount of data stored on the file system."
    },
    {
      "original": "For a production environment, it is preferable that the MGS have separate storage to allow future expansion to multiple file systems.",
      "fix": "For a production environment, it is preferable to have separate storage for the MGS to allow future expansion to multiple file systems."
    }
  ],
  "inconsistency": [
    {
      "original": "The default <emphasis role=\"italic\">bytes-per-inode</emphasis> ratio (\"inode ratio\") for an ldiskfs MDT is optimized at one inode for every 2560 bytes of file system space.",
      "explanation": "This sentence seems inconsistent with the table provided later in the document, which lists different bytes-per-inode ratios for OSTs of various sizes. It would be helpful to clarify how this default ratio applies."
    }
  ],
  "wording": [
    {
      "original": "For best performance in a production environment, dedicated clients are required.",
      "suggestion": "For optimal performance in a production environment, use dedicated clients."
    },
    {
      "original": "However, it is possible to run the MDS and MGS on the same machine and have them share the same storage device.",
      "suggestion": "Alternatively, you can run the MDS and MGS on the same machine, sharing the same storage device."
    }
  ]
}

[Oleg Drokin]

SettingUpBonding.xml

 {
  "spelling": [
    {
      "original": "adress",
      "fix": "address"
    },
    {
      "original": "recieved",
      "no instance found": {
        "no other spelling errors were found": ""
      }
    },
    "grammarIntialized empty object as no grammar errors were found",
    "inconsistencyIntialized empty object as no inconsistencies were found",
    "wordingIntialized with suggestions for improvement",
    [
      {
        "original": "This chapter describes how to use multiple network interfaces in parallel to increase bandwidth and/or redundancy.",
        "suggestion": "Consider rephrasing to 'This chapter explains how to configure multiple network interfaces in parallel to boost bandwidth and ensure redundancy.'"
      }
    ],
    "suggestions for improvement were limited due to well-structured text."
  ]
}

[Oleg Drokin]

SettingLustreProperties.xml

 {
  "spelling": [
    {
      "original": "lustredemo - a simple example of lustreapi functions",
      "fix": "Lustre demo - a simple example of Lustre API functions"
    },
    {
      "original": "Change these definitions to suit",
      "fix": "Modify these definitions as needed"
    }
  ],
  "grammar": [
    {
      "original": "At the time of writing, this support is proposed as a patch but is not yet merged in to the public ANL code base.",
      "fix": "At the time of writing, this support was proposed as a patch but had not yet been merged into the public ANL code base."
    },
    {
      "original": "While conceptually similar to the posix_fadvise and Linux fadvise system calls, the main difference of llapi_ladvise() is that",
      "fix": "Although conceptually similar to the posix_fadvise and Linux fadvise system calls, the primary difference between llapi_ladvise() and these system calls is that"
    }
  ],
  "inconsistency": [
    {
      "original": "The synopsis for llapi_file_open lists both llapi_file_create and llapi_file_open.",
      "explanation": "The synopsis should only include the function being described."
    },
    {
      "original": "llapi_quotactl returns 0 on success, but other functions return >= 0 or < 0 on failure.",
      "explanation": "Return values for all functions should be consistent. It is recommended to use a consistent format throughout the document."
    }
  ],
  "wording": [
    {
      "original": "Currently only RAID 0 is supported.",
      "suggestion": "Note that currently, only RAID 0 is supported."
    },
    {
      "original": "LU_LADVISE_LOCKAHEAD merits a special comment.",
      "suggestion": "Special consideration should be given to LU_LADVISE_LOCKAHEAD."
    }
  ]
}

[Oleg Drokin]

Revision.xml

 {
  "spelling": [],
  "grammar": [
    {
      "original": "continually built as suggestions for changes and improvements arrive",
      "fix": "continually updated with new suggestions and improvements"
    },
    {
      "original": "Only the latest revision of this document is made readily available because changes are continually arriving",
      "fix": "Only the latest revision of this document is made available, as it is continually updated"
    }
  ],
  "inconsistency": [
    {
      "original": " Versions of the manual are continually built...The current and latest revision of this manual is available",
      "explanation": "The text switches between 'continually built' (implying multiple versions) and 'only the latest revision is available'. Clarify whether multiple versions or only the latest version is accessible."
    }
  ],
  "wording": [
    {
      "original": "Suggestions for improvements can be submitted through the ticketing system maintained at",
      "suggestion": "Consider rephrasing to 'Submit suggestions for improvements using our ticketing system:' for better clarity and a more direct tone."
    },
    {
      "original": "the current version of Lustre that is in use on the node can be found",
      "suggestion": "Consider simplifying to 'Find the current Lustre version on your node by:' for easier readability."
    }
  ]
}

[Oleg Drokin]

Preface.xml

 {
  "spelling": [],
  "grammar": [
    {
      "original": "This document does not contain information about basic UNIX* operating system commands and procedures such as shutting down the system, booting the system, and configuring devices.",
      "fix": "This document does not cover basic UNIX* operating system commands and procedures, such as shutting down, booting, and device configuration."
    },
    {
      "original": "The shell prompt used in the example text indicates whether a command can or should be executed by a regular user, or whether it requires superuser permission to run.",
      "fix": "The shell prompt in the examples indicates whether a command can be run by a regular user or requires superuser permissions."
    }
  ],
  "inconsistency": [
    {
      "original": "Red Hat* Enterprise Linux* documentation",
      "explanation": "Inconsistent use of asterisks (*) for trademarks. Use either \"Red Hat Enterprise Linux\" or \"Red Hat* Enterprise Linux*\" consistently throughout the document."
    }
  ],
  "wording": [
    {
      "original": "The Lustre client module is available for many different Linux* versions and distributions.",
      "suggestion": "Consider rephrasing to: \"The Lustre client module supports multiple Linux versions and distributions.\""
    },
    {
      "original": "These web sites provide additional resources:",
      "suggestion": "Consider rephrasing to: \"For more information, visit these websites:\""
    }
  ]
}

[Oleg Drokin]

PersistentClientCache.xml

 {
  "spelling": [
    {
      "original": "PiB",
      "fix": "PB (Petabytes)"
    }
  ],
  "grammar": [
    {
      "original": "Each client uses its own local storage, usually in the form of NVMe, formatted as a local file system for the local cache.",
      "fix": "Each client uses its own local storage, typically in the form of NVMe, formatted as a local file system for caching."
    },
    {
      "original": "The data will be accessible again after the PCC client reboots, mounts the Lustre filesystem, and restarts the copytool.",
      "fix": "The data becomes accessible again after the PCC client reboots, mounts the Lustre filesystem, and restarts the copytool."
    },
    {
      "original": "Any Linux filesystem, such as ext4 on an NVMe device, can be used as PCC cache.",
      "fix": "Any Linux file system, such as ext4 on an NVMe device, can serve as a PCC cache."
    }
  ],
  "inconsistency": [
    {
      "original": "PCC-RW attach ID which is same as the archive ID of the copytool agent running on this PCC node.",
      "explanation": "The term 'archive ID' and 'attach ID' seem to be used interchangeably, but their relationship could be clarified for better understanding."
    }
  ],
  "wording": [
    {
      "original": "the I/O stack is much simpler for the cached data",
      "suggestion": "cached data has a simplified I/O stack"
    },
    {
      "original": "Local file caching reduces the pressure on the object storage targets (OSTs)",
      "suggestion": "Caching files locally alleviates pressure on object storage targets (OSTs)"
    },
    {
      "original": "temporary files do not even need to be flushed to OSTs",
      "suggestion": "there is no need to flush temporary files to OSTs"
    }
  ]
}

[Oleg Drokin]

ManagingStripingFreeSpace.xml

 {
  "spelling": [
    {
      "original": "paremeters",
      "fix": "parameters"
    },
    {
      "original": "remap=\"h3\"",
      "fix": "(remove this, it seems out of place)"
    },
    {
      "original": "ea_inode feature on the MDT:",
      "fix": "Consider adding 'the' before 'MDT:' for clarity"
    }
  ],
  "grammar": [
    {
      "original": "individual files can only be striped over a finite number of OSTs",
      "fix": "Individual files can only be striped across a finite number of OSTs"
    },
    {
      "original": "If using an ldiskfs-based MDT, the maximum number of OSTs over which files can be striped can been raised",
      "fix": "If using an ldiskfs-based MDT, the maximum number of OSTs over which files can be striped can be raised"
    }
  ],
  "inconsistency": [
    {
      "original": "chapter about 'Managing File Striping' ends with section on 'Lustre Striping Internals'",
      "explanation": "The last section seems out of place. Consider moving it to a different chapter or making its connection to the rest of the chapter clearer."
    }
  ],
  "wording": [
    {
      "original": "Lustre inodes use an extended attribute to record on which OST each object is located",
      "suggestion": "Consider rephrasing for clarity: 'Lustre inodes utilize an extended attribute to track the OST location of each object'"
    },
    {
      "original": "the maximum stripe count for a single file does not limit the maximum number of OSTs that are in the filesystem as a whole",
      "suggestion": "Rephrase for better flow: 'The maximum stripe count per file doesn't restrict the total number of OSTs within the filesystem'"
    }
  ]
}

[Oleg Drokin]

ManagingSecurity.xml

 {
  "spelling": [
    {
      "original": "posix-access-control-lists-linux",
      "fix": "posix-access-control-lists-on-linux"
    },
    {
      "original": "subdirectory defined as fileset does not exist on the file system, it will prevent any client belonging to the nodemap from mounting Lustre.",
      "fix": "If a subdirectory defined as a fileset does not exist on the file system, it will prevent any client belonging to the nodemap from mounting Lustre."
    }
  ],
  "grammar": [
    {
      "original": "Lustre Isolation enables different populations of users on the same file system beyond normal Unix permissions/ACLs, even when users on the clients may have root access.",
      "fix": "Lustre Isolation allows for different populations of users to coexist on the same file system, extending beyond normal Unix permissions and ACLs, even if users on the clients have root access."
    },
    {
      "original": "This way the sepol parameter will be stored in the Lustre config logs, letting the servers retrieve the information after a restart.",
      "fix": "In this way, the sepol parameter is stored in the Lustre config logs, allowing servers to retrieve the information after a restart."
    }
  ],
  "inconsistency": [
    {
      "original": "Client-side encryption access semantics",
      "explanation": "The section 'managingSecurity.clientencryption.semantics' mentions that encrypted files and directories behave similarly to their unencrypted counterparts, but then lists several exceptions. It would be more accurate to rephrase this to indicate that there are specific differences in behavior."
    }
  ],
  "wording": [
    {
      "original": "For the Lustre case, block devices are Lustre targets attached to the Lustre servers.",
      "suggestion": "In the context of Lustre, block devices refer to the Lustre targets attached to the Lustre servers."
    },
    {
      "original": "Each encrypted directory tree is protected by a master key.",
      "suggestion": "A master key protects each encrypted directory tree."
    }
  ]
}

[Oleg Drokin]

ManagingLNet.xml

 {
  "spelling": [
    {
      "original": "stoping",
      "fix": "stopping"
    },
    {
      "original": "remap",
      "fix": "(no change, but consider using a more descriptive attribute name)"
    },
    {
      "original": "indexterm",
      "fix": "(no change, but ensure that the index terms are properly defined and used throughout the document)"
    }
  ],
  "grammar": [
    {
      "original": "This initial check may cause a pause equal to <literal>router_ping_timeout</literal> at system startup, if there are dead routers in the system.",
      "fix": "This initial check may cause a pause of up to <literal>router_ping_timeout</literal> at system startup if there are dead routers in the system."
    },
    {
      "original": "LNet can work with multiple rails, however, it does not load balance across them.",
      "fix": "Although LNet can work with multiple rails, it does not load balance across them."
    }
  ],
  "inconsistency": [
    {
      "original": "Managing Lustre Networking (LNet)",
      "explanation": "The document title and section titles use both 'Lustre Networking' and 'LNet'. To maintain consistency, consider using either one throughout the document."
    },
    {
      "original": "Configuring LNet Routes",
      "explanation": "This section is titled 'Dynamically Configuring LNet Routes', but it does not provide information on dynamic configuration. Consider rephrasing the title or adding more content to support the claim of dynamic configuration."
    }
  ],
  "wording": [
    {
      "original": "There are two mechanisms to update the health status of a peer or a router:",
      " suggestion": "Two mechanisms are available to update the health status of peers and routers:"
    },
    {
      "original": "Several key differences in both mechanisms:",
      "suggestion": "The following are key differences between the two mechanisms:"
    }
  ]
}

[Oleg Drokin]

ManagingFileSystemIO.xml

 {
  "spelling": [
    {
      "original": "includs",
      "fix": "includes"
    },
    {
      "original": "remap=\"h3\" condition='l28'",
      "fix": "remap=\"h3\" condition='l2.8'"
    },
    {
      "original": "remap=\"h3\" condition='l2C'",
      "fix": "remap=\"h3\" condition='l2.12'"
    },
    {
      "original": "Lustre 2.14 includs",
      "fix": "Lustre 2.14 includes"
    }
  ],
  "grammar": [
    {
      "original": "the file system is quite unbalanced when new empty OSTs are added.",
      "fix": "The file system becomes quite unbalanced when new empty OSTs are added."
    },
    {
      "original": "Files existing prior to the expansion can be rebalanced with an in-place copy, which can be done with a simple script.",
      "fix": "Existing files can be rebalanced using an in-place copy, achievable with a simple script."
    }
  ],
  "inconsistency": [
    {
      "original": "the pool name is an ASCII string up to 15 characters",
      "explanation": "This statement seems inconsistent with the lack of character limits mentioned elsewhere in the document."
    },
    {
      "original": "OST membership in a pool is flexible, and can change over time.",
      "explanation": "However, it's unclear if there are any limitations or potential issues when changing OST membership."
    }
  ],
  "wording": [
    {
      "original": "The use of large SMP nodes for Lustre clients requires significant parallelism within the kernel to avoid cases where a single CPU would be 100% utilized and other CPUs would be relativity idle.",
      "suggestion": "Consider rephrasing for clarity: 'Large SMP nodes used as Lustre clients require substantial kernel-level parallelism to prevent individual CPUs from being underutilized.'"
    }
  ]
}

[Oleg Drokin]

ManagingFailover.xml:

 {
  "spelling": [],
  "grammar": [
    {
      "original": "For information about configuring a Lustre file system for failover, see <xref linkend=\"configuringfailover\"/>",
      "fix": "For information on configuring a Lustre file system for failover, see <xref linkend=\"configuringfailover\"/>"
    },
    {
      "original": "Even if the MMP block has a clean sequence, <literal>ldiskfs</literal> waits for some interval to guard against the following situations:",
      "fix": "Even if the MMP block has a clean sequence, <literal>ldiskfs</literal> waits for an interval to guard against the following situations:"
    }
  ],
  "inconsistency": [
    {
      "original": "The MMP feature is only supported on Linux kernel versions newer than 2.6.9.",
      "explanation": "This statement seems inconsistent with the rest of the document which does not mention any specific kernel version requirements for other features."
    }
  ],
  "wording": [
    {
      "original": "On a new Lustre file system, MMP is automatically enabled by <literal>mkfs.lustre</literal> at format time if failover is being used and the kernel and <literal>e2fsprogs</literal> version support it.",
      "suggestion": "MMP is automatically enabled on new Lustre file systems created with <literal>mkfs.lustre</literal> when failover is used, provided the kernel and <literal>e2fsprogs</literal> versions support it."
    },
    {
      "original": "To determine if MMP is enabled, run:",
      "suggestion": "To check if MMP is enabled, use:"
    },
    {
      "original": "Here is a sample command:",
      "suggestion": "Example:"
    }
  ]
}