Skip to content

Guideline against "pseudo modules" is problematic #116

@stoobie

Description

@stoobie

The guide says:

NOTE
The following standard is recommended when the documentation is being maintained without a Content Management System (CMS) capable of managing complex interrelations between modules.
The use of reusable text snippet files (or text fragment files) is discouraged due to the complications that can arise due to the complexity they introduce.

Snippet (fragment) file use should be limited to:

  • Standardized admonitions (such as 'Technology preview' and 'Beta' text).
  • Where there is an existing standard between the upstream and downstream communities.

This needs either to be rethought or requires a better explanation.

I think that this guideline is not realistic. When you duplicate the same text in many places, you introduce opportunities for bugs that you can't catch easily. We don't have a CMS, but I have encountered more errors introduced because of needing to manually manage duplicate text than I have because of reusing snippets in our doc repo. I wonder if whoever wrote this made global assumptions about the way that repos are managed, assumptions which perhaps do not apply to all cases.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions