search

abathur / ldmud-doc

A temporary repo for working on a revamp of the documentation system for http://github.com/ldmud/ldmud
0 stars 0 forks source link

document (perhaps code?) metadata #3

Closed abathur closed 8 years ago

abathur commented 9 years ago

Some of our docs, my guess is that it's mostly the older ones, will include metadata. Sometimes this stuff will appear under its own heading (AUTHOR or AUTHORS is a common example), but other times it appears mixed in with the HISTORY section. See https://github.com/ldmud/ldmud/blob/master/doc/efun/net_connect#L45 for an example of this.

My personal inclination is to just cut them instead of trying to figure out what to do with them, but this is mostly just for pragmatic reasons. If we want to preserve these artifacts for historical/nostalgia reasons, the most efficient way to do so is probably just to make a new directive like "meta" or "lore" so that I have a place I can toss stuff like this without needing to waste time pondering what it means.

For an example of why it's a burden to ponder what these things mean and give them more precise semantic markup: There's no clear indication of whether these people are being credited for authoring/changing the feature in question, authoring/changing the document we're looking at, or both! It wouldn't at all surprise me if all of these are true of different documents using similar language and identical section headers.

zesstra commented 9 years ago

I would usually agree as well. However, many of the older documents may originate from a time without some versioning and this may be the only source for this meta data. Therefore I am hesitant to axe it completely. So putting into some optional section ancient history / lore might be the best...

abathur commented 8 years ago

I've made a .. lore:: directive for moving this sort of information into. Marking as decided and completing, though in reality this won't be "done" until I've been through the docs once and created lore sections / moved content as appropriate.