Download Reference Manual
The Developer's Library for D
About Wiki Forums Source Search Contact

Why Everyone Loves Bureaucracy

or

How the West Was Won

To avoid arbitrary changing and updating of documents by all participants in this project, we need to implement a rudimentary system. Otherwise document fixes may go unnoticed and project maintainers might lose track of what people have done to fix draft documents.

The goal is to make sure that changes are at least loosely regulated and audited. Many people have opinions on what needs to go into a document, what needs to be changed, and what needs to removed. It is a little presumptuous to assume consensus will reign in a documentation effort so large. Here we encourage some form of accountability and prior discussion before one chooses to modify a document in any significant way.

That said, there are some levels of modification that really require no discussion at all: things like grammar and spelling errors are often easily fixed as the previewer happens to run across them. Any level of bureauocracy that slows fixing those errors down is counter-productive. Still, should there be any question about sentence structure or documentation accuracy, by all means bring the issue up with one of the principal documenters, the original documenter, project reviewers, or the project leader. Clearly, this effort will account for large volumes of text. There will be lots of errors both in grammar and technical accuracy. There is no doubt that we will benefit from many people proofreading the contributions. But the benefit is lost if the majority of these proofreaders change the documents arbitrarily.

For now, the project leader is to be capable of arbitrary decision for document changes, additions, or removals. This decision is one of expediance, primarily for the sake of maintaining project momentum. The project lead also will arbitrate and make conclusions on matters where no concensus has been reached among contributors. Still the project lead should maintain a level of consideration by maintaining contact with the writers before proceeding with significant changes. This is a request, not a requirement. Likewise, prior to implementing changes, project organizers, principal documenters, and reviewers are encouraged to liaise with the project lead to decide on issues of wiki document presentation.

Principal documentors also may make changes in place without prior discussion but will, for the most part, only do that for changes of lesser importance, changes that are obviously not following the Documentation Style Guide, or changes to accomodate some standard formatting; since part of the principal documentors' job here is to ensure document quality, these people may make grammatical and sentence structure changes as well.

Otherwise, where major changes are felt to be necessary after review of a contribution, principal documenters and reviewers should first make suggestions to the authors in such a way that the same goal for quality is achieved. If the original author disagrees with the principal documenter or reviewer suggestion, he may approach the project lead for a decision. Otherwise, if the original author merely feels incapable of making the changes, the principal documentor that reviewed the section is free to attempt the modification personally.

Finally, all participants -- including project organizers, principal documentors, reviewers, and the project lead -- should discuss any major changes or additions before implementing them. Every level of contributor needs some level of accountability.

All other concerns will be settled outside the saloon in quick draw fashion. JJR reserves the right to challenge contenders to an armwrestling match instead. ;)