Manifold Atlas:Instructions for writing

From Manifold Atlas
(Difference between revisions)
Jump to: navigation, search
(→Scientific style)
m (→Starting a page)
(27 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
<!-- This page outlines the scientific conventions and goals for writing in the Atlas: it also explains the open-editing and author-based options.-->{{DISPLAYTITLE:{{NAMESPACE}}: {{PAGENAME}}}}
+
<!-- This page outlines the scientific conventions and goals for writing in the Atlas: it also explains the open-editing and author-based options.-->{{DISPLAYTITLE:{{NAMESPACE}}: {{PAGENAME}}}}<nonumbers/>
−
This page describes the scientific writing style of the Manifold Atlas.
+
This page describes the scientific writing style and goals of the Manifold Atlas.
+
+
You may also wish to visit the following pages: [[Manifold Atlas:Writing groups|Editing protocols]], [[Manifold Atlas:Author orientation|Author orientation]] or [[Manifold Atlas:User orientation|User orientation]].
== Scientific style ==
== Scientific style ==
−
* The Manifold Atlas aims to be an '''reliable scientific reference''' for researchers and students of manifolds.
+
The best ways to write in the Atlas depends upon the stage of development of a page.
+
+
This section describes the '''general principles''' which should be in operation at all times while writing in the Atlas.
−
* Please write rigorously and clearly for a '''topologically literate audience''':
+
The [[#The evolution of a page|next section]] gives suggestions for writing during the '''various stages''' of the evolution of a page.
−
** i.e. assume that your reader has taken relevant '''introductory graduate level''' courses for the area you are covering.
+
−
* Please give proofs or references to '''peer-reviewed journals''' for all non-elementary statements.
+
* The Manifold Atlas aims to be a '''reliable scientific reference''' for researchers and students of manifolds.
+
** At all times do your best to make correct statements.
+
** If you are unsure about a point, make this clear in the text or consider addressing that point on the [[Manifold Atlas:User orientation#Writing on discussion pages|discussion page]].
−
* As far as possible define the terms and concepts you use:
+
Please write rigorously and clearly for a '''topologically literate audience''':
−
** a quick way to achieve this is to [[Manifold Atlas:Wiki syntax#Hyperlinks|hyperlink]] to [[Wikipedia:Main_page|Wikipedia]] or another web resource if the term is adequately defined.
+
* i.e. assume that your reader has taken relevant '''introductory graduate level''' courses for the area you are covering.
−
* For articles in the [[:Category:Manifolds|Manifolds]] chapter please review the [[Manifold Atlas:Structure of a Manifolds page|suggested structure]].
+
Pages in the [[:Category:Manifolds|Manifolds]] Chapter, the [[:Category:Questions|Questions]] Chapter and the [[Manifold Atlas:Bibliography|Bibliography]] have a canonical suggested structure.
+
* Please think carefully before choosing to depart from this structure.
== The evolution of a page ==
== The evolution of a page ==
−
* It will typically take many edits for a page to reach [[Manifold Atlas:Editorial Policy#Editorial criteria|maturity]].
+
Lets adopt the metaphor of thinking of a page as a plant.
−
* New and young pages bear the [[Template:Stub|Stub]] template indicating that they are under development.
+
Our goal is to plant a healthy seed, grow the seed into a flourishing plant and then finally prune the plant so that it is ready for the "front garden": i.e. publication as a static article in the Atlas.
−
* After a page reaches maturity, the editorial board will organise for it to be [[Manifold Atlas:Editorial Process|refereed]].
+
=== Starting a page ===
+
Your goal in starting a page is to create a useful seed that you or others can then grow.
+
* For links to technical and general information visit the page [[Manifold Atlas:Author orientation|author orientation]].
−
== Open-editing pages ==
+
A healthy seed-page should contain:
−
* Open-editing pages can be edited by any registered user.
+
* a non-trivial piece of information (often a definition),
+
* a link and/or a reference.
−
* Open-editing pages offer the possibility of '''massively parallel''' collaboration for recording, organising and developing information about manifolds.
+
Here is a sample [[Manifold Atlas: A sample seed-page|seed-page]].
−
* Open editing-pages require scientific co-operation and team-work a la Wikipedia.
+
* A seed page may also contain lists of key words which could also appear in the form of [[#(Hyper)links|open links]].
−
* You should feel free to:
+
* Hopefully starting a page is something one can do with 15 minutes to an hour of time.
−
** edit typos,
+
−
** fix mistakes,
+
−
** add hyerlinks,
+
−
** add new sections and subections,
+
−
** improve presentation and organistaion (but think carefully here).
+
−
* You should think carefully before making significant changes to existing text.
+
* Don't forget, we have an [http://manifoldatlas.uni-bonn.de/converter automatic bibiliography] to speed you on your way.
−
* When in doubt about a prospective edit use the discussion page or email the other active users on the page.
+
=== Growing a page ===
−
** If there there is no response after a couple of days, proceed with your planned edit.
+
Once a page is well planted you can begin to grow it.
−
* In general questions of style or point of view should first be raised on [[Manifold Atlas:User orientation#Writing on discussion pages|discussion page]] before edits are made.
+
There is only one strict rule to recall during page development which we mentioned above but repeat here. At all times:
+
* please do your best to ensure that Atlas pages contain correct information and
+
* please do your best to give references or justification for the information you add to the Atlas.
−
* After making significant changes, it is helpful to leave a remark on the discussion page explaining or describing your edit.
+
With regard to the second point, please note that correctly formulated [[Manifold Atlas:References#Open references|open references]] are adequate references in the development phase of page growth.
+
<!-- * Alternate your writing between:
+
** "Free writing" where lay out facts, create [[Manifold Atla:References#Open references|open references]], [[open links]] and don't worry about proofs and not so much about definitions.
+
** "Tightening" where terms are defined, references are filled in and created and justifications are given.
−
== Author-based pages ==
+
* Consider working in teams with "free writers" followed by "tighteners". -->
−
* Author-based pages can be edited only by a '''single author''' or '''team of authors''':
+
−
* Author-based pages offer the possibility for an expert or team of experts to develop information about manifolds in public and over the web.
+
=== Pruning a page ===
+
The aim of the Atlas is to publish its pages by submitting them for evaluation by the [[Manifold Atlas:Editorial Board|editorial board]].
−
* Besides having restricted editing, author-based pages are open to development, editorial review and discussion just as an open-editing page.
+
* If you are working at the final stage of a page, please read the criteria for [[Manifold Atlas:Editorial Policy#Editorial criteria|maturity]].
+
** Please give proofs or references to '''peer-reviewed journals''' for all non-elementary statements.
+
** You may consider [[Manifold Atlas:Uploading PDF files|uploading PDF files]] to give the details of proof without making the web-page too long.
+
** Please carry out a literature search to ensure that the relevant literature is correctly referenced.
−
* All users can write on the discussion pages of author-based pages and provide feed-back, questions or suggestions.
+
=== Refereeing pages ===
+
All pages which have not been refereed bear the [[Template:Stub|Stub]] template indicating that they are under development.
−
* A new author can be added to an author-based page at any time if all the current authors agree to it.
+
* After a page reaches [[Manifold Atlas:Editorial Policy#Editorial criteria|maturity]], the editorial board will organise for it to be refereed: you can read about the editorial process [[Manifold Atlas:Editorial Policy#Editorial criteria|here]].
−
* If all authors agree, an author-based page can be released to become an open-editing page at any time.
+
* If you think a page is mature, please [mailto:{{adminemail}} email the administraitors].
−
** However this is, in general, an '''irreversible process'''.
+
−
* The [[Template:Authors|author template]] appears at the top of each author-base page making the responsible authors immediately visible.
+
== (Hyper)links ==
+
A well-written article will find a '''good balance between''' the following extremes:
+
* too few links and your document is somewhat of a dead-end,
+
* too many links make texts hard to read and can distract the reader.
+
Here are two guideslines for using hyperlinks:
+
* you can use links to both define and emphasise key concepts,
+
* you only need to link a given page once per page or section, unless emphasis is sought,
+
Note that [[Manifold Atlas:Wiki syntax#Open and broken links|open links]], appearing in red, can be useful:
+
* e.g. open links can indicate pages you think should exist but don't right now.
+
For ease of writing on your first draft, simply write your link as <tt><nowiki>[[intended link]]</nowiki></tt>:
+
* later on you, or other users, can fill in the links to make them active '''but'''
+
* but please endeavor to return and fill in open links in a timely fashion.
−
* Please list the names of authors alphabetically.
+
=== Linking to Wikipedia and other web resources ===
+
[[Wikipedia:Category:Differential_topology|Wikipedia]] and other web resources already contain a great wealth of mathematical information and '''there is no point in duplicating this content in the Atlas'''.
+
* Atlas articles will differ from Wikipedia articles in that they assume a higher level of mathematical background and will typically discuss manifolds in greater depth and with greater precision than Wikipedia.
+
* A good heuristic for linking to the web is the following:
+
** use links to Wikipedia and other external web-sites define terms and concepts, assuming the definition there is adequate, but,
+
** do not use Wikipedia as a reference: refer to peer-reviewed mathematical literature.
+
We hope that there will be a '''positive synergy''' between Wikipedia and the Atlas:
+
* Atlas authors may wish to improve and add to Wikipedia articles to define the terms they use,
+
* hopefully in time, Wikipedia can link and refer to articles in the Atlas.

Latest revision as of 09:03, 12 April 2012

This page describes the scientific writing style and goals of the Manifold Atlas.

You may also wish to visit the following pages: Editing protocols, Author orientation or User orientation.

Contents

1 Scientific style

The best ways to write in the Atlas depends upon the stage of development of a page.

This section describes the general principles which should be in operation at all times while writing in the Atlas.

The next section gives suggestions for writing during the various stages of the evolution of a page.

  • The Manifold Atlas aims to be a reliable scientific reference for researchers and students of manifolds.
    • At all times do your best to make correct statements.
    • If you are unsure about a point, make this clear in the text or consider addressing that point on the discussion page.

Please write rigorously and clearly for a topologically literate audience:

  • i.e. assume that your reader has taken relevant introductory graduate level courses for the area you are covering.

Pages in the Manifolds Chapter, the Questions Chapter and the Bibliography have a canonical suggested structure.

  • Please think carefully before choosing to depart from this structure.

2 The evolution of a page

Lets adopt the metaphor of thinking of a page as a plant.

Our goal is to plant a healthy seed, grow the seed into a flourishing plant and then finally prune the plant so that it is ready for the "front garden": i.e. publication as a static article in the Atlas.

2.1 Starting a page

Your goal in starting a page is to create a useful seed that you or others can then grow.

A healthy seed-page should contain:

  • a non-trivial piece of information (often a definition),
  • a link and/or a reference.

Here is a sample seed-page.

  • A seed page may also contain lists of key words which could also appear in the form of open links.
  • Hopefully starting a page is something one can do with 15 minutes to an hour of time.

2.2 Growing a page

Once a page is well planted you can begin to grow it.

There is only one strict rule to recall during page development which we mentioned above but repeat here. At all times:

  • please do your best to ensure that Atlas pages contain correct information and
  • please do your best to give references or justification for the information you add to the Atlas.

With regard to the second point, please note that correctly formulated open references are adequate references in the development phase of page growth.

2.3 Pruning a page

The aim of the Atlas is to publish its pages by submitting them for evaluation by the editorial board.

  • If you are working at the final stage of a page, please read the criteria for maturity.
    • Please give proofs or references to peer-reviewed journals for all non-elementary statements.
    • You may consider uploading PDF files to give the details of proof without making the web-page too long.
    • Please carry out a literature search to ensure that the relevant literature is correctly referenced.

2.4 Refereeing pages

All pages which have not been refereed bear the Stub template indicating that they are under development.

  • After a page reaches maturity, the editorial board will organise for it to be refereed: you can read about the editorial process here.

3 (Hyper)links

A well-written article will find a good balance between the following extremes:

  • too few links and your document is somewhat of a dead-end,
  • too many links make texts hard to read and can distract the reader.

Here are two guideslines for using hyperlinks:

  • you can use links to both define and emphasise key concepts,
  • you only need to link a given page once per page or section, unless emphasis is sought,

Note that open links, appearing in red, can be useful:

  • e.g. open links can indicate pages you think should exist but don't right now.

For ease of writing on your first draft, simply write your link as [[intended link]]:

  • later on you, or other users, can fill in the links to make them active but
  • but please endeavor to return and fill in open links in a timely fashion.

3.1 Linking to Wikipedia and other web resources

Wikipedia and other web resources already contain a great wealth of mathematical information and there is no point in duplicating this content in the Atlas.

  • Atlas articles will differ from Wikipedia articles in that they assume a higher level of mathematical background and will typically discuss manifolds in greater depth and with greater precision than Wikipedia.
  • A good heuristic for linking to the web is the following:
    • use links to Wikipedia and other external web-sites define terms and concepts, assuming the definition there is adequate, but,
    • do not use Wikipedia as a reference: refer to peer-reviewed mathematical literature.

We hope that there will be a positive synergy between Wikipedia and the Atlas:

  • Atlas authors may wish to improve and add to Wikipedia articles to define the terms they use,
  • hopefully in time, Wikipedia can link and refer to articles in the Atlas.
Retrieved from "http://www.map.mpim-bonn.mpg.de/index.php?title=Manifold_Atlas:Instructions_for_writing&oldid=8841"
Personal tools
Variants
Actions
Navigation
Interaction
Toolbox