[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]

UnderstandingLustre.xml

 {
  "spelling": [],
  "grammar": [
    {
      "original": "allows Lustre to leverage the scalability and data integrity features of ZFS for individual storage targets.",
      "fix": "allows Lustre to leverage the scalability and data integrity features of ZFS for individual storage targets;"
    }
  ],
  "inconsistency": [
    {
      "original": "The maximum file size is not limited by the size of a single target. In a Lustre file system, files can be striped across multiple objects (up to 2000), and each object can be up to 16 TiB in size with ldiskfs, or up to 256PiB with ZFS.",
      "explanation": "The text mentions two different maximum file sizes: 31.25 PiB for ldiskfs and 8EiB for ZFS, but then states the maximum file size is limited only by available space on OSTs, which could be confusing."
    }
  ],
  "wording": [
    {
      "original": "No space is reserved on the OST for unwritten data.",
      "suggestion": "Consider rephrasing to 'No space is allocated on the OST for unwritten data' for clarity."
    }
  ]
}

[Oleg Drokin]

UnderstandingLustreNetworking.xml

 {
  "spelling": [],
  "grammar": [
    {
      "original": "the network communication infrastructure required by the Lustre file system is implemented using the Lustre networking (LNet) feature.",
      "fix": "The network communication infrastructure required by the Lustre file system is implemented as the Lustre Networking (LNet) feature."
    },
    {
      "original": "Remote direct memory access (RDMA) is permitted when supported by underlying networks using the appropriate Lustre network driver (LND).",
      "fix": "Remote direct memory access (RDMA) is allowed when supported by underlying networks using the corresponding Lustre Network Driver (LND)."
    }
  ],
  "inconsistency": [
    {
      "original": "LNet permits end-to-end read/write throughput at or near peak bandwidth rates on a variety of network interconnects.",
      "explanation": "This sentence seems to be inconsistent with the rest of the document, which is formal and descriptive. This sentence appears more like a marketing claim."
    }
  ],
  "wording": [
    {
      "original": "In certain circumstances it might be desirable for Lustre file system traffic to pass between multiple LNets.",
      "suggestion": "In some cases, you may want Lustre file system traffic to span multiple LNets."
    },
    {
      "original": "LNet layer is connectionless, asynchronous and does not verify that data has been transmitted while the LND layer is connection oriented and typically does verify data transmission.",
      "suggestion": "The LNet layer is connectionless and asynchronous, and it does not verify data transmission. In contrast, the LND layer is connection-oriented and typically verifies data transmission."
    }
  ]
}

[Oleg Drokin]

UnderstandingFailover.xml

 {
  "spelling": [
    {
      "original": "indication provided by the Lustre software",
      "fix": "indications provided by the Lustre software"
    },
    {
      "original": "RAID 5 or, preferably, RAID 6 storage.",
      "fix": "RAID 5 or, preferably, RAID 6 storage;"
    }
  ],
  "grammar": [
    {
      "original": "In a high-availability (HA) system, unscheduled downtime is minimized by using redundant hardware and software components and software components",
      "fix": "In a high-availability (HA) system, unscheduled downtime is minimized by using redundant hardware and software components."
    },
    {
      "original": "the HA software must be able to completely power off the failed server or disconnect it from the shared storage device.",
      "fix": "The HA software must be able to completely power off the failed server or disconnect it from the shared storage device."
    }
  ],
  "inconsistency": [
    {
      "original": "The Lustre software does not provide redundancy for data; it depends exclusively on redundancy of backing storage devices.",
      "explanation": "This statement seems inconsistent with the rest of the document, which discusses failover configurations and redundancy. Consider clarifying or rephrasing this sentence."
    },
    {
      "original": "OST failover functionality does not protect against corruption caused by a disk failure.",
      "explanation": "This statement appears to contradict earlier statements about OST failover. It would be helpful to provide more context or clarify the limitations of OST failover."
    }
  ],
  "wording": [
    {
      "original": "Availability is accomplished by replicating hardware and/or software",
      "suggestion": "Consider rephrasing to 'High availability is achieved through hardware and/or software replication' for better clarity."
    },
    {
      "original": "the same physical logical unit number (LUN) should be visible from both servers.",
      "suggestion": "Consider rephrasing to 'both servers must have access to the same LUN' for simplicity."
    }
  ]
}

[Oleg Drokin]

TroubleShootingRecovery.xml

 {
  "spelling": [
    {
      "original": "indexterm",
      "fix": ""
    },
    {
      "original": "lctl get_param -n osd-ldiskfs.",
      "fix": "lctl get_param -n osd-ldiskfs.<FSNAME>-<MDT_target|OST_target>.oi_scrub"
    }
  ],
  "grammar": [
    {
      "original": "In such a situation, it is normally required that e2fsck only be run on the bad device before placing the device back into service.",
      "fix": "In such situations, it is usually necessary to run e2fsck only on the faulty device before putting it back into service."
    },
    {
      "original": "LFSCK can verify and repair the Object Index (OI) table that is used internally to map Lustre File Identifiers (FIDs) to MDT internal ldiskfs inode numbers, in an internal table called the OI Table.",
      "fix": "LFSCK verifies and repairs the Object Index (OI) table, which maps Lustre File Identifiers (FIDs) to MDT internal ldiskfs inode numbers in an internal table called the OI Table."
    }
  ],
  "inconsistency": [
    {
      "original": "the LFSCK main engine...linearly scans its local device",
      "explanation": "The text sometimes refers to 'LFSCK main engine' and other times just 'LFSCK'. It's better to stick with one term throughout."
    },
    {
      "original": "--type check_type[,check_type...]",
      "explanation": "In some places, options are comma-separated (e.g., --type), but in others, they are space-separated (e.g., -t). It would be more consistent to use the same separator throughout."
    }
  ],
  "wording": [
    {
      "original": "the LFSCK async request pipeline\u2019s input/output may have quite different processing speeds",
      "suggestion": "the LFSCK asynchronous request pipeline's input/output may have significantly different processing speeds"
    },
    {
      "original": "Control and monitoring of LFSCK is through LFSCK and the lctl get_param command.",
      "suggestion": "LFSCK can be controlled and monitored using LFSCK itself and the lctl get_param command."
    }
  ]
}

[Oleg Drokin]

SystemConfigurationUtilities.xml

 {
  "spelling": [
    {
      "original": "remap",
      "fix": "(no fix, but unclear what 'remap' refers to; provide context or clarify)"
    },
    {
      "original": "cfs21@tcp0",
      "fix": "(no fix, but consider explaining the format of this address for clarity)"
    }
  ],
  "grammar": [
    {
      "original": "The Lustre file system architecture is a POSIX-conformant, high-performance, scalable file systems storage and management services.",
      "fix": "The Lustre file system architecture is a POSIX-conformant, high-performance, scalable file system providing storage and management services."
    },
    {
      "original": "...it does require the sgp_dd package.",
      "fix": "...it does, however, require the sgp_dd package."
    }
  ],
  "inconsistency": [
    {
      "original": "The Lustre timeout is 100 seconds...(later)...default Lustre timeout is 100 seconds",
      "explanation": "The same information is repeated; consider removing one instance for conciseness"
    },
    {
      "original": "The <literal>--failnode</literal> option cannot be used with <literal>--servicenode</literal> option. (later) The <literal>--servicenode</literal> option cannot be used with <literal>--failnode</literal> option.",
      "explanation": "These two statements convey the same information; consider merging or rephrasing for clarity"
    }
  ],
  "wording": [
    {
      "original": "More detailed MDT operations statistics are collected for better profiling.",
      "suggestion": "Collect more detailed MDT operations statistics for improved profiling."
    },
    {
      "original": "The stats-collect utility contains scripts used to collect application profiling information from Lustre clients and servers.",
      "suggestion": "Use the stats-collect utility to gather application profiling data from Lustre clients and servers."
    }
  ]
}

[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"
    }
  ]
}