Frequently Asked Questions
What is an Insight Article
| You will find below an outline of the ideal structure of a Insight article ...
Introduction
A 'scientific' or 'technical' article has a structure. The reader of the
article needs (and wants) to know what the article is all about. The purpose of
the article is described in the first section: the introduction section. This
section can be, and most of the time must be quite short. The details of the
article, which makes up the bulk of the text, are described in the next section.
Story
The second section of the article is the 'story' part. This section describes
in detail what was introduced in the first section. If code is designed (and
possibly implemented) the story should describe in quite a bit of detail *why*
the author designed and implemented the code as it is. The reader is not a
mind-reader and doesn't know what had happened in the head of the author while
s/he was designing the code. If there's a lot of code in the article then at
least twice as many lines of explanatory text should be in the story part of
the article.
Note that the above is just a rule of thumb. If a substantial piece of code can
be clearly explained in just a few lines, that's fine. It is also better in some
articles to use Pseudo code. This is especially true for articles on algorithms
for example where the code would vary from language to language.
Note:
Comment lines in code are not considered easy readable text to the reader.
It is much better to use clear and separate text blocks to explain your code
instead and refer to the actual code where necessary. This is not to say that
the odd small comment in text is inappropriate just that the bulk of what would
normally be code comments should form the text background for your article.
If a piece of code is complicated or difficult to understand, a few short
examples can clarify more than say, a complicated mathematical proof of
correctness.
Never start a discussion with the reader in your article; it is not an opinion
column in a newspaper; the article should be 'true', well written and
preferably not be too long; readers want information and they want it explained
in a clear, concise way. If they want to read something that looks like the
chapter of a book, they know where to find their local library.
Conclusion
The last part of the article should be the concluding part: the benefits of the
code described in the previous part can be described here. If there are
drawbacks, they too should be briefly described here. Don't explain any further
details in this section: they should be in the story section. - There is no minimum size for an article as long as it conforms to the guidelines
- When you post an Article the copyright for the work remains with you, but by posting
it you are implicitly giving Bytes.com permission to use the material and display it on the site.
|
Insight Posting Guidelines
| An article that does not conform to these points is likely to be moved to Writers Corner. Once
there you will be given a chance to correct your article and once it reaches an acceptable form it
will be moved back into the Insight Articles section it was intended for. The following are some clear guidelines on submitting new
articles etc. to the "Insights" section
These guidelines clearly outline what is expected from new submissions
to this area. - The
types of articles suitable for the Insights section are those that inform
members (and guests) on:
- general
procedural instructions on a language - How to approach something
- valuable
coding tips with accompanying text
- useful
procedures and functions with background and textual commentary
- general algorithms giving clear explanation of the
algorithm approach and including “cost”. These should preferably use pseudo
code as they are cross platform
- other
useful articles to the developer
- All articles can be reviewed at any time and if it is felt that further work is required then please contact a moderator with the changes you wish to make
- Articles should be clearly formatted to make them more readable
to the user and should be checked for grammar and spelling.
- Titles should clearly indicate the content of the article and contain any
keywords that would normally be used to find such an article when searching the web.
- The Article must not plagiarize any other source.
- The Article must be factually correct.
- The Article must be written in good clear English.
- The Article must be laid out well with appropriate use of text formatting such as bold and italics.
- All code in an Article must be within code tags ( [code] ... [/code] ).
- The Article must list any reference materials the author used in writing them.
- Articles are subject to the normal posting guidelines in that they may not contain
- Foul language
- Personal attacks
- Email addresses
- Political content
- Religious content
- Links to sites with inappropriate content or to competing forums
- Information on the production or procurement of malicious code
If you see an article on this site that breaks point 7 then in the first instance please contact an Administrator. |
Comment Posting Guidelines
| A post that does not conform to standard posting guidelines will be deleted. Any poster who repeatedly breaks the guidelines will be subject to the following punishments (in order) from an Administrator, site Moderator or Moderator:
a warning, a temporary site ban, a permanent site ban. - The content of a comment should be related to the Article it is made in reply to. This content may be a critique of the article,
an indication of how useful the article was (or wasn't) or a note on the technical content of the article.
- Comments should be fairly succinct, e.g. a few sentences, 1 or 2 short paragraphs.
- Comments are subject to the normal posting guidelines in that they must
- Use clear English
- Not use leet or text speak
- Not be in all capitals (it is considered to be shouting)
- Not be in all bold or all italic
- Comments are subject to the normal posting guidelines in that they may not contain
- Foul language
- Personal attacks
- Email addresses
- Political content
- Religious content
- Links to sites with inappropriate content
- Information on the production or procurement of malicious code
- If you feel that a posted article violates any of these guidelines (including copyright infringement) please DO NOT post a comment; contact an Administrator.
| | |
