Policy

  1. Subpages should contain non-spoily information of the type currently contained in the on-line game help. Please put spoiler information in the appropriate place in the SpoilerArchive.

  2. Regarding edits:

    • NeilStevens: Currently, users are asked to discuss in advance any major changes to the Documentation section, because those documents are being synchronized with the in-game documentation.

    • MayLith: Please do not modify the Documentation. While wikis are an open-editing environment, the Documentation section of this wiki is a special case. Please do not change anything within Documentation unless you are a moderator, a game developer, or you have been given explicit permission to do so. We are currently evolving a means for general users to provide documentation suggestions in a way that will not impact the main body of the Documentation.

    • TheFalcon: NOTICE: It is now acceptable for any user to alter documentation, to fill in holes, provide updates etc. Please note, however, that it would still be a good idea to discuss any major changes beforehand, and it is of course possible that unhelpful or spoily changes will be removed by others. Do NOT put spoilers in the documentation. If you are uncertain as to what is spoily, ask in the discussion section. It might be a good idea to record any changes made in the ChangeLog as well, simply for history's sake, and also to provide information for in-game docs should the need arise.

Discussion

NeilStevens: Instead of doing this, please document here the logging requirements of the documentation. We lose the benefits of the wiki for the documentation if we lock it down to a few people. That's how the in-game docs got out of date in the first place.

MayLith: I understand what you are saying, Neil, truly... but that is opening us up to a huge amount of work in terms of cleaning up assorted messes. If we request -- not lock -- but request, that only some people work on the docs, and make sure they know what they are doing, that will take care of what I believe you are concerned about.

NeilStevens: If the burdens of coddling the in-game documentation are too great for this wiki to work as intended, then I would favor dropping the whole idea of keeping a change log and merging the wiki back into the game. If this wiki is going to get held back by the in-game docs then there was no point to a Documentation section of the wiki at all.

MayLith: Also, please read my comments in my 'please read' post again on GeneralDiscussion, as I created a provision for general contribution. It provide for safe, easy-to-handle means of contribution for anyone who has a great idea, including those who can't write well and/or are not well-versed in English. If that method works well, we can always bring on more helpers if need be to avoid bottlenecks.

NeilStevens: I'll comment there.

MayLith: AFAICT, what exists of the wiki doc is already far better, in terms of spoiler elimination/etc, than the in-game doc, and it can only improve from there. I don't mind distributing care of the documentation to a number of people (and in fact, that's already the case), but if you want to open it up to everyone for total chaos, I'll simply wash my hands of the whole thing, as that way madness lies. Yes, a changelog is absolutely needed, but there are some people who should not be changing things. Either that, or we'll be doing one heck of a lot a lot of reverting.

It's very late for me and I need to get to sleep. I did not intend for any of the above to be harsh; I was just trying to get my thoughts down before I lost track of them.

P.s. At the top of this page, there is a clause about reporting problems to administrators. IMHO, a list of administrators (or a link to a list of them) would be appropriate there.

NeilStevens: If you're going to be possessive of it then yes I suggest you stop working on it before you start snarling and biting people who innocently look to improve it. I suggest you instead get a CVS account and work on the in-game docs where you'll get nearly no help at all, and will be able to keep it as out-of-date as you like.

I have edited the problem-reporting text to address your issue.

GregSweetman: Not really wanting to step into an argument here (what with being relatively new and everything), but I think both of you have some points. Firstly, MayLith is right in that at the current stage, opening everything to everyone is a bad idea. It is inevitable that you will get held back in the setting up of the initial wiki structure if you are having to go and correct / edit things that people have posted in the wrong place.

On the other side, NeilStevens is correct in that the whole purpose of the wiki is to have anyone able to add anything at any point, without having to go through a vetting process to get their suggestions / changes seen. If something is wrong, then let the people change it.

I think what you need to do, although the concept of this was rejected before, would be to restrict the editing of the documentation pages until the inital information is there. Once the initial grounds have been set, people will be far more likely to put things in the right place, and you can even delegate the work of sorting out bad spelling and grammar to someone (who then won't also be trying to fix / write the initial structure). At the moment though, those who are innocently looking to improve it may well (as I think has been shown before) actually just be helping to make a big mess, which doesn't improve anything. I wouldn't call MayLith possessive over the wiki, I mean, what use is a wiki if no-one can find what they are looking for. It makes more sense to set up the structure, and *then* open it to the world.

MayLith: Thank you, Greg. That's all I was ever trying to say in the first place.

Speaking of "snarling and biting people who innocently look to improve it", I'm feeling somewhat snarled at right now, and I'm only trying to make an improvement. I think your concerns regarding the burdens you envision are simply a snapshot taken out of a continual process, and if you give it some time, it will resolve itself. Quite frankly, the biggest thing slowing me down right now on Documentation (and teaching others how to work on it) is this very discussion.

This is a new wiki, and growing pains are to be expected. For a while there, it was just a few of us setting up basic structures, and it was easy to change things around *and* start to evolve policy and methods as we went, even though it was chaotic. Now we have new faces (and old friends), and it's become a happier and busier place, and even more chaotic, since we haven't yet evolved procedures to deal with all situations. That's normal, if a bit frustrating at times.

Greg is exactly right in that the greatest damage being done right now is by people innocently trying to help. That is The main issue here is education.

  1. People need to realize the Documentation is a special part of the wiki, and why it is special
  2. We need to build a mindset regarding Documentation that includes:
    1. not making frivolous changes
    2. careful logging of every change

    3. reminding one another to be careful (speaking of which, GregSweetman -- you changed Documentation/Skills/MagicDevice a) after I asked folks not to (though with Neil's argument, that's debatable) and more importantly b) without an entry in the changelog. *wink* Thanks for fixing the link, though!)

    4. self-correcting after blather/damage occurs (a normal part of the wiki process)

There's probably even more points that could be made. I attempted to begin that education with my 'please read' post over on General Discussion, and there's still more scattered about. One thing that should be done is to place a brief explanatory header on each and every page in the Documentation which explains what the situation is, what to do and how to do it -- that would help a LOT. Many stubs aren't even pages yet, though, which is part of why I asked for helpers. Aside from importing stuff, I want to put them on initializing stubs and prefacing them before someone randomly comes along and blathers there instead. (And the other thing is that some of those stubs need to be munged together, which, if I get time tomorrow or late tonight, I'll start working on.)

Once that education starts to take hold AND once the basic framework of the Documentation gets established, I don't forsee any unsurmountable problems with turning the whole Doc section loose to the winds... and I'd prefer it that way, anyhow.

NeilStevens: That all sounds reasonable, much better than just declaring wiki practice to be "chaos" and shutting it down. But, I have another question then: Why again do we want to go to all this trouble, to keep the in-game docs up to date? Will this turn out to be practical in the end? I begin to have doubts. Talking about "frivolous" changes will only discourage copyediting and "minor" technical corrections, that is, the very things that passers-by are going to be able to fix! I think discouraging them will be self-defeating.

MayLith: For goodness' sake, Neil, make up your mind. I was not the one declaring wiki doc to be chaos and therefore worth shutting down. (I am saying that the entire wiki is currently chaotic and that it will get better.) You were the one saying "work on the in-game docs where you'll get nearly no help at all, and will be able to keep it as out-of-date as you like". Do you want the help updated or not? I seem to remember you saying somewhere that you would be grateful if I (or anyone else for that matter) could de-spoilerize/de-angbandize/etc the game documentation. (If I am wrong about that, I apologize.)

The inevitable reality of game documentation is that it will probably always lag the game itself, especially now that we have popular modules such as Theme, and we've got 2.3 CVS and 3.0 in the works as well. But we can certainly make the doc better than what it currently is. You were the one mentioning spoilers, inaccuracies, and references to other games. I simply picked up that flag and have attempted to carry it, my impetus being to try to free you up to do more important things like game dev.

WHY do we want to go to all this trouble? My motives are these: Because when I was invited to be a moderator on the forum, and then made one on the wiki, I devoted myself to this game (even more than I had already done previously, as a player.) Better documentation means a better game, overall, and a better game will, in the end, mean more and happier players.

Yes, I think it's practical, though it may take some time to pan out and will probably involve inevitable joggles along the way. Educating about "frivolous" changes will only cause those who are truly devoted to the game to pay more attention to what is going on. Regulars will visit (and, with education, be correctors) far more often than randoms are, so I believe that that argument does not apply in this case.

I completely agree with you that after the doc has settled down, random foo passersby should not be discouraged whatsoever, but in fact *encouraged*.... but I don't think we are ready for that quite yet. Get the structure ready, and tag all the stubs, get people educated and understanding what's going on... it will be a very, very nice product IMHO. An evolving one (as inevitably it will be) but a very nice one.

NeilStevens: Well wait. My position all along has been "Update the wiki as well as possible. Keep a change log so that the in-game docs can be updated." I thought that you agreed, and that the latter part of that position is why you wanted to lock the docs. I thought your goal in calling for restrictions was to prevent unlogged changes. Am I wrong there?

I can support some rules in order to aid porting wiki improvements (which are great and as appreciated as ever), but I don't want to see this early flurry of improvements followed up with ossification.

MayLith: MayLith's thoughts spelled out:

  1. I agree with "update the wiki as well as possible."
  2. I agree with "keep a change log so that the in-game docs can be updated."

  3. Yes, I do want to prevent unlogged changes. But that's not the only reason why I want random passersby to leave the docs alone for right now.

    1. I do NOT want to physically lock them.

    2. I do, however, want for people who do not understand what is going on, and/or who do not have the skills, to leave docs alone for a time until I (and others) finish some *major* munging. E.g. If I have blank stubs for 10 pages, and in the back of my head I'm eventually going to munge them into a single page, (or worse, combine them with a partial tree someplace else) then I do not want some one to randomly come along and create 10 pages out of nothing which I'll then have to cope with. (And yes, I made those stubs simply because the doc is HUGE and I was trying to get a handle on things. Placeholders make a good referent to push around and think about. Think of it as top-down pseudo-code, which you mess with until you're happy with it, and *THEN* expand into true code (or in this case, doc.))

    3. In the meantime (during the leave-it-alone phase), I am more than willing to:
      1. accept any/all suggestions, preferably in a fashion that will not directly impact the doc itself (and then incorporate it as needed)
      2. accept, and train, helpers to share out the work

I don't want ossification to happen either, Neil. It'd be bad for the game. Don't predict the future based on the bad old past, especially when we have this wonderful new wiki format to help us. Yes, it will be rocky for a while, but I think it will work out fine.

Also, keep in mind that over time there will be the semblance of an initial flurry here. That is part of the growth of the wiki and (in the case of the doc) the fixing of the glaring errors, removal of spoilers, etc etc. Once that gets done with, I would be willing to bet that the traffic in the Doc section will dramatically slow down, perhaps with the exceptions of:

If, aside from these exceptions, traffic does slow, that's fine; it's the sign of a mature document. If some of our resident verbal artists want to further refine our grammar, and our resident game artists want to further elucidate with germane game examples, great.

What it comes down to is this: Why is a document not being changed regularly?

  1. No one cares (or knows) about the content.
  2. Nothing needs to be done.
  3. No one has the time to change it.

As long as the answer is #2, I won't worry. #1 depends upon education, advertising and proper linking. In my case, #3 can sometimes be an issue, which is why I'm taking on help.

FearofFours has already made his comment (see my wiki page). I have also asked him to tell me if there is anything I can do to make his job easier.

GregSweetman: Yes it's true I edited the Documentation/Skills/MagicDevice as you described, but in my defense I would say that I was following the intention of the rules you set out, not the letter. The actual *content* of the file (i.e. the documentation) hasn't changed, so anyone reading it would find no change to the document.
As for point b) you have specified in another thread that you considered edits without a comment to be 'minor' edits, and would be against a comment for every single little typo correction (clogging up the RecentChanges page and everything...). Again, I was following the implied intention here. (p.s. Please don't take this the wrong way, it's not meant to sound like a "well you said..." type response, I'm just giving my reasons).

While I can see the need for recording of *changes* to the documentation, do you think it would be required, or even wanted, to record such a minor edit as this?
(p.s. your edit just over-wrote this one - I assume your editlock had expired - doesn't matter in this case because I always copy my edits to a notepad window before saving them... *just in case*)

MayLith: Actually, I did think about it, Greg. The content didn't change, and in your case, it didn't affect the link -- you just made the link *work*. However, regarding changing/fixing wiki links in documentation and logging those -- that's something that needs to be discussed, preferably not on this page. (I can envision some situations where logging would be a necessity, and it comes down to: Can *everyone* follow a hierarchy (I doubt it), or do I establish a blanket rule?)

My posting about minor edits had to do with my own personal habits re: comments in the comment box. It didn't have to do with documentation. Minor edits, even emplacing a period or fixing spelling on a single word, to Documentation *DO* need to be logged, as that's exactly the sort of thing that FearofFours needs to know about. There are times when you will not see a comment-box comment when I change the Documentation, but I always log it in the ChangeLog, which is where it needs to go anyway. Granted, if I make 10 changes in 5 minutes (which happens) I may only post one entry in the ChangeLog, but that entry will reflect the summary of the net change.

JulesBean: I am concerned about the whole idea of having the same basic document (the ToME documentation) in two different formats in two different places (in the wiki and in the source tree) without any automatic tool to generate the one from the other. It seems to me that this is a lot of work for someone (poor FearofFours) to keep the two up to date. Perhaps my concerns are unfounded, feel free to prove me wrong.

MayLith: No kidding. Why else would I be so paranoid about the changelog?? What is happening on this wiki is the evolution of a greatly revised document that will go into the game. I've said that before, and yes, I'm worried about it, which is why I'm banging on this so hard. If you share my concern, then help me by volunteering to help, and keep an eye on Doc.

NeilStevens: You miss the point.

NeilStevens: One of the main functions of our wiki engine is to take generically marked-up documents and transform them into HTML. One reason I come down hard on abuse of tables, use of http URLs for internal links, and the insertion of HTML into the mark-up is that I want to support transformations to other formats. Exporting to a format that ToME could use is something I've wanted all along.

NeilStevens: Automatic export would not be error-prone the way manual ports of changes would be, and would not let the in-game docs fall behind. Yes, it's nice that right now we have someone willing to volunteer to port over the changes, but he's just a volunteer.

NeilStevens: If something happens to his free time or interest, then where will we be? Automatic generation won't ever go away.

SoulWynd: Hm, Neil, I could code a small standalone program to convert them, but I would need to know what kind of design you guys want. On the other hand, if I have the patience to, I could create a macro that does it whenever a page is saved. The macro one is not likely to happen, my patience has been really short lately. I barelly program my own stuff as it is now.

NeilStevens: I don't know enough about MoinMoin's export capabilities to say what the design should be.

SoulWynd: Anything phyton can export to. Tome help files are plain text but what I meant was, what should be converted into what? For an example, how should the program convert headers, comments? How would it handle tables? What colors should it use? etc... Btw, I'd rather do a win32 standalone program than a moinmoin export macro. At least for me it would be easier, unless we have a phyton expert around.

NeilStevens: I know MoinMoin supports multiple output formats. I just haven't looked further into it. When I do get a chance to work on ToME the docs are not a priority of mine. This site is, ToME 2.3 testing is, and beyond that Arda is. I'd write new features for this site before writing the export, but I'd be willing to assist others who choose to write the export.

The exporter would have to write out ToME's oddball home-grown help markup format. Tables would have to be laid out with spaces. What colors should be used is hardly an architectural question.

My server does not run Microsoft software. Writing your app using their proprietary libraries instead of the standard POSIX stuff, or the standard library of any given language, would not be productive.

NeilStevens: This seems like a bad time to do this, as MayLith hasn't posted for nearly two weeks, but then again, the possibility of her absence is exactly the kind of thing the wiki needs to be prepared for.

This restrictive docs policy is an ever-present danger of driving people off and stagnating the wiki. Because of that, I really don't like the idea of the wiki having a long-term requirement of being held back by an outside document.

I understand that Martin, Megan, and others have done a lot of hard work, and doing everything you've envisioned would be a lot more hard work. And worse, if people like the illustrious maintainer and I do all the things we envison (like that big old ToME 2.3 skills change), your work will keep piling up!

Yet I must ask: what is the goal? What do you presently hope to achieve by having a connection between the wiki docs and the in-game docs? What is gained by having a nice, new, easy-to-edit system set up for maintaining things like docs, but then turning away most would-be contributors to it?

I can see having the restrictions and the changelog as a transitional policy, to be used to keep the current in-game docs updated while the wiki catches up. But once that's done, then I think the time comes to start generating the in-game docs from the wiki. And I think that needs to be the goal if we're to tolerate having the wiki harnessed by a changelog and stuff.

We've been around the merry-go-round before, but what's the goal, and how close are we to attaining that goal? Is enough progress being made that we can justify to ourselves proceeding with the plan?

Thank you.

TheFalcon: Now, being new to documentation, I haven’t witnessed all the struggles and torment you developers have gone through to get this far. However, I thought I would provide my views anyway, and give an attempt at making them objective.

I believe the restrictive policy is, at present a good idea, and may well remain to be so. It prevents people from fiddling in small ways without logging the changes, (such as developing stubs insufficiently, or leaving them lying around), and other things which prevent the documentation from being helpful. I see innaccurate, out-dated, sprawling documentation as worse than an accurate and well organised, if restricted, section.

I see the documents section as having the primary aim of being readily available help and guidance to those who wish to play  ToME  . At the moment the docs are unhelpful, and the restrictive policy does make them look frightening, but I see this as a necessary evil. Once the wiki docs are brought up to date, quite possibly based on the in-game help, (since this is probably the most accurate source of documentation), the helpfulness will increase, and I should think they will advance faster than the in-game docs. As I see it, the wiki documents section will not be ‘held back’ by an outside document, but once the catch up phase is complete, the wiki should be able to develop in parallel, or advance. The change log can be used for reference, and hopefully, the in-game docs will be able to follow this, keeping up with the changes in the wiki, and primarily based on it.

Any changes to the game (like the 2.3 skills change) will of course mean more work for the wiki docs team, but that is to be expected anyway. This will really be part of ongoing maintenance, and the bigger the change, the more work, naturally.

I cannot say how close the documents are to achieving the goal of providing up to date usefulness, but will have a better idea after some work on the magic section.

TheFalcon: Please read the notice near the top of the page regarding edits for current policy...

Wiki Policy/Documentation (last edited 2006-01-07 19:34:35 by TheFalcon)