This project page is semi-protected.

Wikibooks:Editing guideline

From Wikibooks, open books for an open world
Jump to navigation Jump to search

Perfection not required; or, the joy of editing

It is a wonderful thing when someone adds a complete, well-written, final draft to Wikibooks. This should always be encouraged.

However, one of the great advantages of the wiki system is that incomplete, poorly-written first drafts of textbooks can evolve into polished, presentable masterpieces through the process of collaborative editing. This gives our approach an advantage over other ways of producing similar end-products. Hence, the submission of rough drafts (but not too rough) should also be encouraged.

One person can start off with an overview or a few random facts. Another person can add a minority opinion. Someone else can round off the content with additional perspectives. Yet another can play up an angle that has been neglected, or reword the earlier opinions to a more neutral point of view. A following person might have facts and figures or a graphic to include.

As all this material is added, anyone can jump in and refactor to turn it into a more cohesive whole. Then more text will be added, then more refactoring, and the module will gradually evolve ever-closer to the ultimate final draft.

During this process, the module might look like a first draft—or worse, a random collection of notes and factoids. Rather than being horrified by this ugliness, we should rejoice in its potential, and have faith that the editing process will turn it into brilliant prose.

Of course, we don't have to like it; we even, occasionally, criticize really substandard work, in addition to simply correcting it. The most important thing, though, is to correct it if it can be corrected. For text that is beyond hope, we have gotten into the habit of removing the offending content to the corresponding talk page, or, in cases where the content obviously has no redeeming merit whatsoever, deleting it outright. The latter action should not be done lightly, however.

On editing styles

Generally, different people here have different editing "styles". Some people edit lightly, and focus on contributing new content. Others prefer to greatly expand existing "stubs" and improve content. Some like to make relatively small copy-editing, linking, and page-naming changes. There's room for all of these on Wikibooks.

There are also different editing styles in the sense of how bold people are willing to be. Generally, most of us think we should be bold in updating pages. Virtually no one behaves as though previous authors need to be consulted before making changes; if we thought that, we'd make rather little progress. Quite to the contrary, some of us think you should not beat around the bush at all—simply change a page immediately, when you see something problematic, rather than to discuss changes that need to be made. Discussion, from this point of view, is a last resort. Then there is a more intermediate view, according to which dialogue qua dialogue should be respected, but at the same time a minor tweak early on can avoid a flame war. In this view, to edit radically or not will often depend on the context—which seems reasonable enough.

Again, there is a place for all of these attitudes on Wikibooks.

With large deletions or replacements, it might be better to suggest changes in a discussion, lest the original author get discouraged and quit posting. One person's improvement is another's desecration, and nobody likes to see their work just flushed without warning.

So, whatever you do, try to preserve information. Reasons for removing bits of a module include:

Alternatives include:

  • rephrasing while keeping the content
  • moving text within a page or to another page (existing or new)
  • adding more of what you think is important to make a page more balanced

If, in your considered judgment, a page simply needs to be rewritten or changed substantially, go ahead and do that. But preserve any old contents you think might have some discussion value on the talk page, along with a comment about why you made the change. Even if you delete something that's just plain wrong, odds are that it got there because someone believed it was true, so preserve a comment that it is in fact wrong to inform later editors.

In any event, whether you decide to edit very boldly or to make inquiries on talk page first, please bear in mind that Wikibooks is not a discussion forum. Wikibooks can be a very energetic place, and it's best for the project as a whole if we concentrate our energies on improving modules rather than defending our pet theories, ideologies, religions, etc. Some consideration of Etiquette wouldn't hurt.

Further suggestions for the etiquette and method of editing

  • Perhaps use the discussion page to first preserve content that could be added back in error and explain why the content is being altered. Use your browser's back button to copy-paste the content to be quoted, or to reduce mistakes use two browser windows or tabs.
    Since discussion pages can get lengthy and all content is preserved in the history, one paragraph on what is wrong and why is probably all that is needed most of the time. The exception might be when someone drastically refactors a page, in which case use a subpage of the discussion page and link to it from the discussion page.
  • Use the top of discussion pages to help organize and plan collaboration efforts. For example use an outline of what still needs to be done (a to-do list for example) and who is currently working on what parts of the model. Also include links to other related discussion pages, categories or any important notices at the top so people don't accidentally delete them by mistake.
    As the top of discussions pages or any discussion section gets long, archive old business and discussions. This helps keep discussion pages current, relevant and understandable, which is most important for keeping discussion pages usable and readable. Use archive names with the same name as a section name whenever possible so people can find discussions later on.
  • Summarize long discussions and retain conclusions of long discussions, so that others can get involved later or get up to speed quickly. While this isn't required per se, doing so goes a long way towards keeping collaboration with others pleasant and discussions fresh so everyone can keep up with developments.
  • Sign your posts on talk pages (but not your contributions to actual book content).
  • Fill in an edit summary before saving your changes.
  • Preview your edits before you save.
  • Avoid using bots.
  • Contribute what you know or are willing to learn about
  • Create stubs responsibly and make obvious omissions explicit.
  • Explain jargon.
  • Integrate changes, instead of just appending your thoughts at the end of a page
  • Define and describe
  • Cite your sources, and use proper references.
  • Avoid statements that will date quickly
  • Check your facts
  • Avoid blanket statements
  • Avoid self-references
  • Avoid creating deeply nested sections.
  • Aim for brilliant prose, accessible structure, wide-ranging and in-depth coverage, and verifiable contents so that your book may one day join the ranks of featured books.
  • Last, but not least, some numbering scheme ought to prefix all sections below the fixed sections (i.e. all are categorized as 'temporary topics' even though most of each are eventually separated and archived.) The section ordinal number prefix serves notice when something no longer appears in the ordinal list of sections as it contains only expired discussions, and pertinent information is retained.