[edrocks]

I wrote an XLSX(spreadsheet) writer in golang a few years ago and still maintain it. I also deal with a bunch of other several hundred to thousand page docs semi regularly and the best advice I have is to make use of the index, bookmarking pages, and a ton of cmd+f searching for various keywords.

I was talking with a lawyer friend the other day who confirmed a good index is really a must for long documents.

[ergothus]

In my experience, a good index doesn't just show where any usage is, it also covers where it is significant (bolding, sometimes subcategorizing).

In the big texts (granted, for me these are almost always RPG books, but I've read/used a lot of those) that difference is essential, and the difference between the good ones (e.g. GURPS) and the bad ones (most WW books...the ones that HAVE indexes) is very noticeable and definitely impacts not just ease-of-use, but effective-ness-of-use. Being able to really get/refresh uses of different bits has a direct impact on whether I apply those concepts consistently and correctly or whether I do something that works well enough.

This definitely describes what happens when changing code too, but we don't have that same option for "significant usage". We can get every usage, usage numbers counted by file, and definitions, but not when a use is significant. We rely on tools to get those numbers, because any kind of manually supported index (of code) is doomed to failure, much as most texts fail to have indexes, or at least fail to have very useful ones.

I wonder if that "significant usage" is something we can do something about. What does that even mean? I've been looking at code linguistically a lot and I definitely can see how we can use syntax to better indicate the focus of code (vs trivial but necessary side bits), is there a way to mechanically note that? It would still require coders to write that way, but frankly I feel we need better (or at least more clear) best practices on that front anyway. If we expand our lexicon of constructs, and mechanically make use of it, it becomes testable, reliable, and still more communicative that the current "this feels good to me, therefore I declare the code 'more readable'" approach.