style.md maintainability: split into multiple files?

[abhinav]

EDIT(2022-03-03): The style guide is now split into multiple files and merged back into a single file with tooling to ensure existing links continue to work.

style.md is a massive Markdown file. It'll only get bigger.
I'm opening this to discuss the possibility of breaking it up into multiple, more maintainable files.

Requirements:

• Required: Sections of the style guide are written in different Markdown files, organized however we choose.
• Nice to have: Individual files have a top-level header (#) instead of 3-level deep (###).
• Nice to have but strongly preferable: automatic generation of table-of-contents because what we have right now is unwieldy
• Absolutely required: Existing links MUST NOT break. We link to sections in the style guide in internal code reviews all the time. It's safe to assume that others who rely on this guide do the same. Whatever we do here, we must ensure that existing links to style.md or any of its headers continue to work.

Prior work:

• We've had some success with mdox to keep code samples outside Markdown files in Fx. It does not support file includes or TOC generation.
• Asciidoc supports include directives to import code samples and other asciidoc files, and asciidoc-reducer reduces them into a single file. This includes a "leveloffset" option, which offsets header levels of included files. But this requires writing asciidoc instead of Markdown, which, even if I could sell a new markup format, would rename style.md to style.adoc and break all links. That makes it a non-option.

Proposal:
I don't have a solution to suggest yet, but what I think we want is:
Something that lets us specify a root Markdown file or configuration file that
references other Markdown files in-order.

If the root file is a Markdown file, we'll need a custom "include" directive.
This may automatically increment header levels based on the current section
or accept an argument specifying the offset like asciidoc.
If the root file is a configuration file, this isn't required because we likely have more freedom on the format.

The thing that consumes the root file may also optionally generate a TOC
depending on how much we want that feature.

But most importantly, it generates a final Markdown file that gets written out over our existing style.md.
That ensures that existing links to style.md continue to work,
and also lets us preview the result when we publish PRs.
(We could add a CI check to ensure the file is up-to-date,
or have the workflow update the file when the PR is created.)

Anyway, as I said, this isn't a concrete proposal yet.
Just gathering opinions and looking for input on both
whether this is a good idea, and how we might want to go about it.

[mway]

We might want to enumerate more specific existing (or even hypothetical) maintenance issues that we intend to hedge against (ideally other than "too much scrolling", because that just redistributes the same problem from a single file across many discrete files - i.e., what was a search problem becomes a selection+search problem, even with reasonably good classification).

For the sake of discussion, as a counter-point, I can imagine that - if split into many documents - it could become harder to find/refer to guidance across the docs that make up the guide. E.g., instead of "Where was that in this doc again? <search>" it becomes "Was that in this doc? <search> Nope, which other doc would it be in? <shell grep/find> <open first match> <search> <repeat until found>".

One related thing that I've been thinking about is generating a static site (go.uber.org/guide or uber-go.github.io/guide, in order of personal preference), and using that for new links moving forward (with the expectation being that eventually, all or nearly all references would point to the static site). If we're going to introduce a pipeline that consumes discrete docs to produce a final doc, we might as well have it generate a site too.

[abhinav]

Good points. From the point of view of consuming the guide, there isn't an issue with a large guide. One big ctrl-f friendly document is the way to go.

From the point of writing and maintaining it, I've found it a bit annoying to navigate the nearly 4000 line Markdown file and keep the TOC up-to-date. But I agree that it's possible for this problem to just be transferred into searching across multiple files.

I've been thinking about is generating a static site

I was also considering that with the "split to multiple files" situation.
I think either way, whatever we choose should still have the final style.md to keep existing links valid.

[mway]

Also, one obvious organization could just be splitting each of the existing top-level bullets into their own docs, e.g.:

• Intro -> intro.md
• Guidelines -> guidelines.md
• Performance -> performance.md
• Style -> something_other_than_style.md (TBD)
• Patterns -> patterns.md
• Linting -> linting.md

That's at least simple enough that where to find/place guidance becomes (relatively) unambiguous, and probably doesn't add any noticeable maintenance overhead.

[abhinav]

Yeah, that's valid.

Just to experiment, I tried a per-section version as well.
I don't love the names I picked, but here's what it ends up with:

atomic.md          error.md                import-group.md    prefix-unexported-var.md
builtin.md         exit-main.md            index.md           ptrs-to-ifaces.md
chan-one-zero.md   explicit-field-tags.md  init.md            public-embed.md
consistent.md      fire-and-forget.md      intro.md           reduce-nest.md
container-cap.md   fmt-const.md            lint-intro.md      reduce-scope.md
copy-slice-map.md  fmt-func.md             lint-runners.md    strconv.md
defer.md           func-group.md           local-var-decl.md  string-backticks.md
dont-panic.md      func-names.md           long-lines.md      string-to-byte.md
else-return.md     func-opts.md            map-init.md        struct-init.md
embed-top.md       group-decls.md          mutex-zero.md      test-tables.md
enum-one.md        header.md               naked-params.md    time.md
error-name.md      iface-compliance.md     nil-slice.md       top-var-decl.md
error-types.md     iface-recv.md           no-globals.md      type-assert.md
error-wrap.md      import-alias.md         package-names.md

I used pandoc and a third-party filter to combine these together and generate a TOC.

Features:

• One file per level 3 section (mostly)
• Automatic TOC
• The header.md is the "Uber Go Style Guide" header. It's separate to keep it out of the Table of Contents generation.
• All includes are in index.md which defines the top level structure (Intro, Guidelines, Performance, ...).
  • Not exactly. The error.md file was long so I split out the subsections into separate files, so that's the only other file with includes.

Issues:

• Links to other headers assume the combined file. That is, the link to "nil is a valid slice" cannot reference nil-slice.md, and instead uses #nil-is-a-valid-slice--the name of the header in the final combined file. But that's not the end of the world.
• It is very slow to generate the final document.
• Pandoc silently turns fenced code blocks without a language specified (```) into 4-space indented code blocks and I haven't found a way to disable that.
• Pandoc uses inline links ([foo](bar)). There's a flag to use reference links, but then it always uses reference links. It doesn't preserve.

This was just a test and we shouldn't use this exact separation or method to combine, but I think file name to header mapping can be obvious if we try. We can also do folders for section if we really want, but I suspect that's not necessary.