• MayLith
• Neil doc chatter

NeilStevens: There is a way around it, one I've advocated over and over: Drop the in-game docs as they exist today, and use the wiki to generate their replacement. Even just shipping HTML docs would be a fair tradeoff, I think.

• I don't see any way around this. The path you're going toward, with a few people doing the docs, already failed. If it worked,

  • MayLith: If what worked? Sorry.... I'm unsure of the pronoun.

  you wouldn't have to do this much catch up in the first place, would you?

  MayLith: In what way has it failed? It seems to be going along quite swimmingly, at least from what I hear from FearofFours and a few others. Re: dumping the existing in-game docs and creating new from scratch, that was my basic idea in the first place, even if it might not seem that way. Here is the basic roadmap that I had in mind:

  1. Import all current in-game doc. Status: In progress.

  2. Delete all spoilers and fix/ameliorate assorted other foo. See here for a mission statement with further details. Status: In progress. Yes, it's a lot of work, but it's badly needed.

  3. Once the dust from all of the above has settled, establish a new framework (which, IIRC, FearofFours has already done here. Status: Completed, at least the basic version.

  4. Copy over anything valuable from the existing help into the new framework, to avoid re-creating the wheel. If something is REALLY not worth it (e.g. TANG) then ditch it and start anew, or incorporate some of its material into somehting new.
  5. Supplement the existing material with new doc.

  If, as you suggest, we completely delete everything in the Documentation section and start over again from scratch, it will take even longer to get somewhere... though I'll admit to the desire from time to time.

  NeilStevens: In what way did the small-cabal system of documentation fail? Simple: The 2.2.7 docs are replete with triply obsolete ( ToME -> Pernangband -> ZAngband -> Angband) information, and left full of major ToME-era spoilers. We just got two bug reports this week from someone who read the docs, trusted the docs, and found out they were totally wrong.

  • MayLith: Since when was that my fault? If you want the wiki docs completely on spec 100% of the time, put me on salary. (No, no, no.... I'm joking!!! Though, actually... *wink*) Anyway, the docs were out of spec before I got here, and (no doubt) were also out of spec before Darkgod ever created ToME. We're doing the best we can. And yes, I know you know that. The fact that they are/were out of spec cannot be definitely proven to be due to the cause of a small number of people working on it, though. No comparative large-cabal data exist relative to roguelikes AFAIK. (And no, I'm not trying to make a specious argument, but raising the subject of bug reports on problems on old documentation while we're trying to revamp it seems a touch unfair to me.)

  And sure, for right now, things are getting a lot better, but people come and go. If we don't get a system set up so that people can fix things as they go out of date, then the next time we all wander off the docs will go badly out of date again. Then, all this work will have to be done over again by the next group of contributors. So, I hope that in the foreseeable future the changelog system will be removed, and the docs will be as open as any reference material on the wiki. That is, people like us will monitor for vandalism or mistakes, but anyone will be allowed to make fixes and improvements as necessary.

  MayLith: So, in essence if not in name, you are blaming me for the obsolete game help which I never wrote in the first place and am spending hours of my free time to update. Fine.

  • If you want it that way, I'll stop working on the docs. Do what you want with it. I'll go back to playing the game and doing other moderating.

  • If you don't want me to stop working on the docs, please don't complain about the docs being in transitory status. I have asked for qualified help. Greg Sweetman offered, but I haven't seen him about lately. I have also proferred numerous avenues for people to suggest changes, but have had no takers but for ErisDiscordia, who I need to follow up with, and ReenenLaurie, who I've not seen lately and also need to follow up with. If others want to offer, I would be more than happy to oblige.

  Two bug reports is a tiny number for the in-game help. You, of all people, should know that people come and go and are going to complain about whatever. I've lost numerous characters to inaccuracies in the help, which in part is why I undertook this blasted project in the first place. If I was writing bug reports on the in-game help, then please consider the entire Doc changelog to be my (incomplete) bug report.

  I would just as soon get rid of the changelog myself since it's a major pain, but it is useful to FearofFours, even if he doesn't incorporate everything done here. I respectfully suggest you check with him about this decision. Oh, and FWIW, especially since this is a text environment: I'm not mad at you, Neil, even if reading this may make it seem that way. I'm just tired and frustrated. Please don't take any of this in a hostile manner. I respect you deeply for what you are doing, and I want whatever is best for this game. If what is best boils down to mean that I'm wrong, I can accept that.

  NeilStevens: OK, back up. We have a miscommunication. I'm not saying you failed. I'm not blaming you. I'm saying that the system you're proposing, where a few select people have the sole authority to keep the docs up to date, is what has failed in the past. And again, I appreciate everything you're doing in the docs, but I'd rather you not worked on them if you're going to be uncomfortable with other people touching them.

  • MayLith: I think part of the miscommunication is that there are at least three (4?) issues going on here -- maybe more:

    1. I don't have the historical perspective that you, FearofFours, MassimilianoMarangio and others have. In some ways, my ideas may sometimes be a drawback, since I might be likely to repeat old mistakes (which you want to prevent, and that makes complete sense to me). In other ways, they are a fresh look with new eyes.

    2. You are comparing past history of doc update (via mechanisms unknown to me) with the present. Whether this is significant or not, I don't know... but as a newbie, this kicks up a yellow flag for me. Just because a different mechanism didn't work in the past doesn't necessarily mean that THIS mechanism won't work, either. Then again, maybe it does... but I don't think it should be taken as an automatic given, either.
       1. Whether the mechanism should exist at all, due to respect to the function of the wiki, is something else again.
    3. I have been, and am still trying to feel out how documentation should be maintained here on the wiki, from practical and logical viewpoints. I have a number of ideas about that, and they break down into two phases:
       1. the rework phase
       2. the maintenence phase

       Re: the changelog and other people touching things: It's the rework phase that gets my back up, mainly because major chunks of things are getting shifted around. The macro page is a prime case in point. Completely aside from the copyright foo (which has now been taken care of), I had listed out subheadings from the MacroFAQ on the main documentation page purely as a notepad. I had intended, later on, to move ALL of those subheadings (or at least those that survived my axe <g>) onto one single macro page. But in the meantime, well-meaning people came along and expanded many of those individual subheadings into their own pages, creating *LOTS* of extremely shallow pages with, at times, rather questionable content. Not good wiki, AFAIK. What I am trying to do is: (after the fact note -- I'm repeating repeating myself! <g> Anyway, take it for what it's worth)

       1. Get all this stuff copied over.
       2. Get out the worst of the dreck (I believe I mentioned turning the Doc upside down and shaking it hard.)

       3. Refine it into the structure FearofFours has proposed (or whatever it ends up as.) This will probably involve setting up the new structure and then copying over (if we really want to do that.)

       4. End changelog and enter maintenence phase
       Regarding maintenence, we might:
       1. Turn it loose and kiss it goodbye.
       2. Encourage others to enter proposed changes in a chatter section on the page in question, then have a group of volunteers munge changes in as needed, or
       3. Something else?

    4. I don't mind help. I'll take all the help I can get! I just want helpers who a) know the game, b) can write well, and c) have some sense of organization.

  It's not worth it to have updated docs if you're going to have a hard time every time someone uses the wiki as designed and intended.

  • MayLith: See the above. However, after reading all the many comments you've had to say about how bad the current docs are and even creating RBS because you didn't want to recommend the in-game help, I think you're being just a teeny tiny bit hyperbolic on that one. <-- See the smile?

  If you'd like to keep working, but it's only the changelog that's the problem, just forget it. Drop the whole idea. Just make the wiki work as well as you can, incorporating the in-game docs, but forget making it easy to port the changes back.

  • MayLith: Keeping a changelog is easy enough for me to do -- when I said it was a major pain, I guess I was just whining, sorry (embarassed grin). It will, though, probably become impossible to maintain once we reach maintenence phase -- some people will inevitably forget to log changes.

  Once the wiki documentation tree is done, we (I or whoever volunteers) can write an export tool that generates a standalone set of HTML docs from the wiki. This way the game can ship with updated documentation in the tarball.

  • MayLith: That'd be wonderful. I do, though, again recommend we get FearofFours' & MM's input on all this. I'm trying to take the long view, especially since this whole thingamabob is going to have to be changed again (or supplemented anyway) once 2.3 is released... ooogh.

  NeilStevens: Having a few people with CVS accounts who make documentation fixes didn't work, so having a few people on the wiki allowed to make documentation fixes won't work either. We've gotten enough input. If this issue is causing any hassle at all, and it is judging by this discussion and others before it, it's causing more hassle than it's worth. So, I'm making a decision here: it is not the responsibility of the wiki contributors to care about the contents of the documentation that ships with ToME. People on the wiki don't have the power to fix what's in CVS, so it's not right to expect them to try to keep synchronized with that.

  • MayLith: I do think it was a worthwhile discussion, though. At any rate, my interest in working with FearofFours and MM was because they have great ideas. Working together without staying in lockstep should still be possible. (And for that matter, I know that FF isn't incorp'ing all my changes, and that doesn't bother me at all.)

  I'd like to see the wiki version of the documentation go off on its own and be the best documentation possible. When the docs here are more complete and better than what's in ToME, then we can solve the issue of shipping these docs with ToME at that time. Until then, let's only worry about the wiki on the wiki. I wasn't exaggerating at all. I don't want people who are getting good work done to be inconvenienced or annoyed at all, if possible. I'd easily sacrifice updated docs in order to keep all of you happy and productive on the wiki. I'd rather sacrifice the ToME-included docs in the short run to get better Wiki and ToME-included docs in the long run, though. So let's do just that.

  MayLith: OK. I gave this a lot of thought last night: If you don't mind, I wish to keep using the change log. Not for syncing, but for my own convenience. I've noticed that I use the log myself, to check where I left off doing something, track to-do's, etc., and when I see that MM's done something, that's helpful for coordination purposes, too. Also, the change timestamp helps; I've gone back to view old versions a few times and even reverted on myself a few times when I FOD'd up a doc beyond all redemption.

• ..later... Yes, this helps. I'm not stressing about following the old structure anymore.

  NeilStevens: Great. And as for the changelog, RecentChanges isn't enough for you? If not, use the changelog as you see fit, of course.

  MayLith: The text string in RecentChanges isn't long enough, and I don't have the patience to do a zillion diffs, so yes, the log helps. (Have you ever looked at the changelog? ) I may change my mind as time goes on.

  NeilStevens: No, I've never looked in it. My wiki time is spent checking for spam, managing bug reports, and things like that.

  MayLith: I suspect you have at least as little free time as I do, but respectfully, you ought to wander around at least a little bit and have some fun, even if it's not in the ChangeLog (which isn't exactly fun.)

  NeilStevens: Well, I actually did play some ToME this week, and have started moving my character sheets from the Ladder to here. Happy? heh.

  MayLith: Actually, yes. I'm glad to hear it. Also, I'm on day 2 of a 4-day vacation, so I'm happy in general. But having fun is always a good thing. Speaking of which, I'm soon going off to spank s'more Q's...

If it seems I pick on your language a lot, it's because you write a lot, and what you write will have broad influence on this wiki. Please don't take it personally.

MayLith: None taken, and thank you for taking the trouble to explain. I'll nix trueart from my vocabulary.