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

grammar/semantic specifics for documenting history #16

Closed abathur closed 7 years ago

abathur commented 8 years ago

The current form I am using for documenting history is a "field-list" field titled "history". The form/syntax is :history <verstring> <verb>: <explanation/notes>, but let's look at something more concrete.

The short lifecycle of efun308 makes it an interesting case study (obsolete/efun308, https://raw.githubusercontent.com/abathur/ldmud-doc/master/source/obsolete/efun308.rst), so I'll use it as an example:

:history 3.2.1@1 introduced:
:history 3.2.6 changed: renamed to :efun:`set_environment`
:history 3.2.9 changed: not available if driver is compiled without USE_DEPRECATED.
:history 3.3 removed:

This sets up to address a few questions about how we can refine the terms we use:

  1. I started off with "history" as the name of this because it's what we've historically called the section, but I prefer the grammatical clarity we get if we change the name to "version" and will do so if no one objects. Then, our section would look like this:

    :version 3.2.1@1 introduced: :version 3.2.6 changed: renamed to :efun:set_environment :version 3.2.9 changed: not available if driver is compiled without USE_DEPRECATED. :version 3.3 removed:

  2. The tradeoff is that it's easier to infer that history adds the history section, than it would be to infer the same of version for someone unfamiliar with the source (admittedly a small concern). One hedge against this might be changing the section header from "HISTORY" to "VERSION HISTORY"? Thoughts?
  3. If you refer to http://abathur.github.io/ldmud-doc/build/html/obsolete/efun308.html you can see how the verb is used (at current, we can always remix how this looks). At the moment I am just using "introduced", "changed", "deprecated" and "removed" (I think...). These aren't code-enforced choices yet, though I'd like to make them so. To drill down:
    • I'm not married to "introduced", but I chose it because we use "added" all the time to describe adding functionality to something that exists.
    • I don't really like how vague "changed" is, but it was the simplest way to shoehorn most of the existing history lines in without having to decide how to categorize each. Additionally, some existing history lines document a lot of different changes, and a more specific set of verbs might require splitting a lot of those up and having a line for each verb. "modified" might be a good replacement for changed. Thoughts on modified v. changed v. multiple more specific verbs?
    • Any other thoughts on this set of verbs?
  4. I'm curious what others think about the tense used for both the verbs in 3 above and the actual version history explanation. Past tense for both? past for the verb, present for the explanation? present for both?
abathur commented 8 years ago

I had planned to implement the change from "history" to "version" for describing the above, but in doing so I've found that the way docutils handles some document metadata fields (including version!) interferes with doing it this way. I tried several different ways of getting around this, and while it's inevitably still possible, I feel like it's becoming more trouble than it's worth for the more natural-English construction of ":version <introduced/changed/removed>: ".

We could possibly still use something like ":ldmud <introduced/changed/removed>: ", and it should be a relatively trivial change if we thought that worked better. I don't presently see that as more desirable all around, though.

abathur commented 8 years ago

WRT to verbs used with this syntax, I'm going to settle on the following:

I like modified for definitional reasons, but I think changed is easier to type/read/think. I am inclined to keep the past tense for both the verbs and messages. Marking as closed.

abathur commented 8 years ago

Reopening but marking as decided; will close when verbs and such are actually code-enforced.