Please Read this Guideline before Making Your Own Contribution

From WikiContent

(Difference between revisions)
Jump to: navigation, search
Current revision (21:55, 4 February 2009) (edit) (undo)
 
(10 intermediate revisions not shown.)
Line 1: Line 1:
-
Welcome! Thanks for taking the time to read this (meta)contribution.
+
Thank you for taking the time to read this (meta)contribution.
-
With a limit of 500 words, a contribution should not have any need of any headings, so don't worry about that aspect of wiki markup. External links and normal text formatting are fine (see [http://www.mediawiki.org/wiki/Help:Contents here] for more details on MediaWiki formatting). However, as the intent is also to publish accepted contributions in book form, each contribution should be able to stand on its own and should not rely on an external link in order to make sense.
+
With an upper limit of around 500 words, a contribution should not have any need of any headings or footnotes, so don't worry about those aspects of wiki markup and formatting. External links and normal text formatting are fine (see [http://www.mediawiki.org/wiki/Help:Contents here] for more details on MediaWiki formatting). However, as the intent is also to publish accepted contributions in book form, each contribution should be able to stand on its own and should not rely on an external link in order to make sense. If there is an external link or book reference that has value, try to incorporate it into the flow of the main text rather than introduce a ''further reading'' or ''references'' section. It is possible that a ''further reading'' section may prove useful for some articles, but there is no guarantee that such sections will make it into the book even if they are included on the web site. As each contribution is intended to be standalone, contributions should also not link to one another. For the book, cross-linking also imposes a reading order and makes the assumption that the other item has been accepted for the book.
-
As already mentioned on the [[97 Things Every Programmer Should Know|main page]], the recommended length of a contribution is between 250 and 500 words (you may find [http://www.wordcounttool.com/ this] handy if you don't have a shell and <code>wc</code> to hand). Contributions that are spell-checked (US English) are always appreciated! O'Reilly have a [http://oreilly.com/oreilly/author/stylesheet.html stylesheet] which you can read through if you're interested. Not all of it is applicable to the ''97 Things'' format, but you may find it useful nonetheless.
+
As already mentioned on the [[97 Things Every Programmer Should Know|main page]], the recommended length of a contribution is between 400 and 500 words (you may find [http://www.wordcounttool.com/ this] handy if you don't have a shell and <code>wc</code> to hand). Contributions that are spell-checked (US English) are always appreciated! O'Reilly have a [http://oreilly.com/oreilly/author/stylesheet.html stylesheet] which you can read through if you're interested. Not all of it is applicable to the ''97 Things'' format, but you may find it useful nonetheless. Note that items should not contain any graphics (illustrations, graphs, cartoons, etc.), just text.
-
Advice that is focused on programming should be as independent of programming language as possible. The set of contributions is intended to appeal to programmers across the board, so items on metaprogramming in Ruby, hardcore templates in C++, or the ins and outs of annotations in Java would not be appropriate. Of course, programming languages can be mentioned, their features discussed, and code fragments included, but the advice offered should not be so specific to a single language that it does not speak to readers working with other languages. If you include code, it will be easier to read if inline code elements are distinguished like <code>this</code> and if blocks of code are shown
+
Advice that is focused on programming should be as independent of programming language as possible. The set of contributions is intended to appeal to programmers across the board, so items on metaprogramming in Ruby, hardcore templates in C++, or the ins and outs of annotations in Java would not be appropriate. Of course, programming languages can be mentioned, their features discussed, but the advice offered should not be so specific to a single language that it does not speak to readers working with other languages. If you include code, it will be easier to read if inline code elements are distinguished <code>like this</code> and if blocks of code are shown
like this
like this
 +
 +
But please do not use this block style for anything else, such as bullets. MediaWiki has other ways of expressing this kind emphasis and layout, for example:
 +
 +
* Bullets should appear like this
 +
 +
* Not like this
 +
 +
Note that code is included in the word count.
Of course, advice does not specifically have to be about code or involve code fragments. There are a lot of things a programmer should know, and code is but one part of the larger picture we're trying to paint in ''97 Things''. Areas of interest range from the low level to the high, from programmatic to philosophical, from algorithms and data structures to agility in development.
Of course, advice does not specifically have to be about code or involve code fragments. There are a lot of things a programmer should know, and code is but one part of the larger picture we're trying to paint in ''97 Things''. Areas of interest range from the low level to the high, from programmatic to philosophical, from algorithms and data structures to agility in development.
-
And don't forget to include your bio or to put your name on your contribution (see line below). Many thanks and I look forward to your contributions!
+
And don't forget to include your bio or to put your name on your contribution (see line below for an example). Many thanks and I look forward to your contributions!
By [[Kevlin Henney]]
By [[Kevlin Henney]]

Current revision

Thank you for taking the time to read this (meta)contribution.

With an upper limit of around 500 words, a contribution should not have any need of any headings or footnotes, so don't worry about those aspects of wiki markup and formatting. External links and normal text formatting are fine (see here for more details on MediaWiki formatting). However, as the intent is also to publish accepted contributions in book form, each contribution should be able to stand on its own and should not rely on an external link in order to make sense. If there is an external link or book reference that has value, try to incorporate it into the flow of the main text rather than introduce a further reading or references section. It is possible that a further reading section may prove useful for some articles, but there is no guarantee that such sections will make it into the book even if they are included on the web site. As each contribution is intended to be standalone, contributions should also not link to one another. For the book, cross-linking also imposes a reading order and makes the assumption that the other item has been accepted for the book.

As already mentioned on the main page, the recommended length of a contribution is between 400 and 500 words (you may find this handy if you don't have a shell and wc to hand). Contributions that are spell-checked (US English) are always appreciated! O'Reilly have a stylesheet which you can read through if you're interested. Not all of it is applicable to the 97 Things format, but you may find it useful nonetheless. Note that items should not contain any graphics (illustrations, graphs, cartoons, etc.), just text.

Advice that is focused on programming should be as independent of programming language as possible. The set of contributions is intended to appeal to programmers across the board, so items on metaprogramming in Ruby, hardcore templates in C++, or the ins and outs of annotations in Java would not be appropriate. Of course, programming languages can be mentioned, their features discussed, but the advice offered should not be so specific to a single language that it does not speak to readers working with other languages. If you include code, it will be easier to read if inline code elements are distinguished like this and if blocks of code are shown

like this

But please do not use this block style for anything else, such as bullets. MediaWiki has other ways of expressing this kind emphasis and layout, for example:

  • Bullets should appear like this
* Not like this

Note that code is included in the word count.

Of course, advice does not specifically have to be about code or involve code fragments. There are a lot of things a programmer should know, and code is but one part of the larger picture we're trying to paint in 97 Things. Areas of interest range from the low level to the high, from programmatic to philosophical, from algorithms and data structures to agility in development.

And don't forget to include your bio or to put your name on your contribution (see line below for an example). Many thanks and I look forward to your contributions!

By Kevlin Henney

This work is licensed under a Creative Commons Attribution 3


Back to 97 Things Every Programmer Should Know home page

Personal tools