Ns-3-users-guidelines-for-posting - Revision history

Tomh: /* Screenshots */

2024-04-28T22:47:26Z

Screenshots

← Older revision		Revision as of 22:47, 28 April 2024
Line 26:		Line 26:
	==== Screenshots ====		==== Screenshots ====

	Please try to avoid sending large screenshot files. Instead, copy the relevant information from the terminal and paste it into the body of your message.		Please try to avoid sending large screenshot files. Instead, copy the relevant information from the terminal and paste it into the body of your message. This reduces the size of everyone's inbox, and also makes the content more searchable.

	If you are reporting a problem that requires a visualization to show the issue, a screenshot is OK.		If you are reporting a problem that requires a visualization to show the issue, a screenshot is OK.

Tomh: /* Information to include in your message */

2024-04-28T22:46:49Z

Information to include in your message

← Older revision		Revision as of 22:46, 28 April 2024
Line 23:		Line 23:

	=== Information to include in your message ===		=== Information to include in your message ===

			==== Screenshots ====

			Please try to avoid sending large screenshot files. Instead, copy the relevant information from the terminal and paste it into the body of your message.

			If you are reporting a problem that requires a visualization to show the issue, a screenshot is OK.

	==== Platform ====		==== Platform ====

Tomh: /* Work through the tutorial, all of it */

2024-04-28T22:43:24Z

Work through the tutorial, all of it

← Older revision		Revision as of 22:43, 28 April 2024
Line 7:		Line 7:
	=== Do your homework ===		=== Do your homework ===

	==== Work through the [https://www.nsnam.org/~~ns-3-24~~/~~documentation~~/ tutorial], all of it ====		==== Work through the [https://www.nsnam.org/docs/tutorial/html/index.html tutorial], all of it ====

	==== Read the [http://www.nsnam.org/documentation documentation] about models and the reference manual ====		==== Read the [http://www.nsnam.org/documentation documentation] about models and the reference manual ====
	==== Search the [https://groups.google.com/forum/#!forum/ns-3-users Google Groups] to see if your question was asked before ====		==== Search the [https://groups.google.com/forum/#!forum/ns-3-users Google Groups] to see if your question was asked before ====

Pdbarnes: /* Preliminaries */ Add exceptions and crashes section

2017-03-10T18:15:15Z

Preliminaries: Add exceptions and crashes section

← Older revision		Revision as of 18:15, 10 March 2017
Line 27:		Line 27:
	If you are reporting a problem such as a installation failure, please report enough details about your platform to allow a maintainer to reproduce.		If you are reporting a problem such as a installation failure, please report enough details about your platform to allow a maintainer to reproduce.

	==== Code ~~snippets~~ ====		==== Source Code ====

	Create the simplest possible script which illustrates the issue you are facing. It’s almost always impossible to give a helpful reply when looking at a snippet from a larger script, or worse a snippet which refers to code models not part of the distribution.

	Use the attachment feature for posting scripts; only short snippets (less than 10 lines) should be inline.		Use the attachment feature for posting scripts; only short snippets (less than 10 lines) should be inline.

			Create the simplest possible script which illustrates the issue you are facing.

			It’s almost always impossible to give a helpful reply when looking at a snippet from a larger script, or worse a snippet which refers to code models not part of the distribution.

			If there is the remotest chance you changed something in an ns-3 module, state that up front. Attach your modified files and a minimal main script that triggers the problem.

			==== Exceptions and Crashes ====

			Exceptions and crashes are a normal part of debugging. Learn to use a debugger; this isn't the right place to ask what to do next when the <tt>gdb></tt> prompt appears. When someone (or an error message) suggests running your script in a debugger, expect to do some work to learn more about what's going on, beyond just the stack trace. it's almost always impossible to make useful suggestions from just that. Don't waste everyone's time, including yours, by just posting it and asking for help. Reread the previous section on [[#Source Code]].

	== Posting Guide: How to ask good questions that prompt useful answers ==		== Posting Guide: How to ask good questions that prompt useful answers ==

Tomh: reorganize a bit

2016-01-13T22:48:26Z

reorganize a bit

@@ Line 1: / Line 1: @@
 {{TOC}}
 == Posting Guide: How to ask good questions that prompt useful answers ==
 This guide is intended to make more productive use of the ns-3-users group by recommending best practices for posting questions and answers.  Please keep in mind that over 5000 people subscribe to this group, so it is common courtesy to follow this guidance.
@@ Line 9: / Line 43: @@
 This guide is freely adapted from the R Posting Guide (http://www.r-project.org/posting-guide.html)
-=== The list: ===
+=== Good manners: ===
 ns-3 is open source software, constructed and maintained by volunteers. They have various reasons for contributing software and participating on the group, but often have limited time.  Please help them quickly understand the details about your problem, and please avoid asking questions that have already been answered.
 Follow etiquette and professionalism guidelines found in [https://www.ietf.org/rfc/rfc1855.txt RFC1855] and [https://www.ietf.org/rfc/rfc7704.txt RFC7704].  Please read these if you haven't already.
@@ Line 20: / Line 52: @@
 Note:  if moderators find posts that lack etiquette or professionalism, we will follow an escalation path that will result in private and/or public warnings, and eventual ban from the group if behavior is not modified.
 === Which group (or mailing list)?: ===
@@ Line 47: / Line 65: @@
 Please do not post the same message to both lists; pick one.  ns-3 maintainers read both lists.
 === Do your homework before posting: ===
@@ Line 119: / Line 139: @@
 * Threatening not to use the software if you cannot get your question answered. Even when intended as a statement of fact, this tends to create negative attitudes.
 * Posting the same question more than once per day (in different threads).
 === Final words: ===

Tomh: /* Responding to other posts: */

2016-01-05T06:00:45Z

Responding to other posts:

← Older revision		Revision as of 06:00, 5 January 2016
Line 104:		Line 104:
	** No profanity, and never do jokes about sex, religion, culture, or about someone's misuse of the English language. You can be funny without being offensive.		** No profanity, and never do jokes about sex, religion, culture, or about someone's misuse of the English language. You can be funny without being offensive.
	** Avoid interactions that could be considered to be harassing or mocking someone else. If you are interacting with someone who you feel is not making a fair effort to follow the list guidelines, it is best to just stop replying further, rather than to post something out of anger or frustration or to try to get the last word in.		** Avoid interactions that could be considered to be harassing or mocking someone else. If you are interacting with someone who you feel is not making a fair effort to follow the list guidelines, it is best to just stop replying further, rather than to post something out of anger or frustration or to try to get the last word in.
			** Keep in mind also, if writers are trying their best not to be offensive, readers should try not to be offended too easily.
	** Do not plead (e.g., repeatedly asking the same question or with capitalization or many exclamation points) if you do not get the answer you want as quickly as you may want it.		** Do not plead (e.g., repeatedly asking the same question or with capitalization or many exclamation points) if you do not get the answer you want as quickly as you may want it.
	* Never post something if you are angry. Wait some hours and re-read your message if you composed it while you was upset.		* Never post something if you are angry. Wait some hours and re-read your message if you composed it while you was upset.

Tomh: /* Responding to other posts: */

2016-01-05T05:49:28Z

Responding to other posts:

← Older revision		Revision as of 05:49, 5 January 2016
Line 102:		Line 102:
	** If no one has posted a reply, then post your reply.		** If no one has posted a reply, then post your reply.
	* Use professional writing guidelines to convey information in a clear, efficient way		* Use professional writing guidelines to convey information in a clear, efficient way
	** No profanity, and never do jokes about sex, religion, culture, or about someone's misuse of the English language. You can be funny without being offensive.		** No profanity, and never do jokes about sex, religion, culture, or about someone's misuse of the English language. You can be funny without being offensive.
	** Avoid interactions that could be considered to be harassing or mocking someone else. If you are interacting with someone who you feel is not making a fair effort to follow the list guidelines, it is best to just stop replying further, rather than to post something out of anger or frustration or to try to get the last word in.		** Avoid interactions that could be considered to be harassing or mocking someone else. If you are interacting with someone who you feel is not making a fair effort to follow the list guidelines, it is best to just stop replying further, rather than to post something out of anger or frustration or to try to get the last word in.
	** Do not plead (e.g., repeatedly asking the same question or with capitalization or many exclamation points) if you do not get the answer you want as quickly as you may want it.		** Do not plead (e.g., repeatedly asking the same question or with capitalization or many exclamation points) if you do not get the answer you want as quickly as you may want it.
	* Never post something if you are angry. Wait some hours and re-read your message if you composed it while you was upset.		* Never post something if you are angry. Wait some hours and re-read your message if you composed it while you was upset.

Tomh: /* Posting Guide: How to ask good questions that prompt useful answers */

2016-01-05T05:48:59Z

Posting Guide: How to ask good questions that prompt useful answers

← Older revision		Revision as of 05:48, 5 January 2016
Line 3:		Line 3:
	== Posting Guide: How to ask good questions that prompt useful answers ==		== Posting Guide: How to ask good questions that prompt useful answers ==

	This guide is intended to make more productive use of the ns-3-users group by recommending best practices for posting questions and answers. Please keep in mind that over ~~4000~~ people subscribe to this group, so it is common courtesy to follow this guidance.		This guide is intended to make more productive use of the ns-3-users group by recommending best practices for posting questions and answers. Please keep in mind that over 5000 people subscribe to this group, so it is common courtesy to follow this guidance.

	If one of the project maintainers responds to your question by citing this guide, please re-read the guidance before asking your question again.		If one of the project maintainers responds to your question by citing this guide, please re-read the guidance before asking your question again.
Line 44:		Line 44:
	Questions such as "Does ns-3 support <insert-protocol-model> because I'd like to reuse it if so?" should always be asked on ns-3-users. Questions such as "Is anyone developing a model of <insert-protocol-model> for contributing back to ns-3?" are appropriate for ns-developers or ns-3-users.		Questions such as "Does ns-3 support <insert-protocol-model> because I'd like to reuse it if so?" should always be asked on ns-3-users. Questions such as "Is anyone developing a model of <insert-protocol-model> for contributing back to ns-3?" are appropriate for ns-developers or ns-3-users.

	New users, or users seeking help in performing a particular task are probably more ~~confortable~~ with ns-3-users. The ns-developers mailing list is friendly as well, but it assumes that you have ~~a thorough~~ knowledge of ns-3, and out-of-scope posts will usually be redirected to ns-3-users.		New users, or users seeking help in performing a particular task are probably more comfortable with ns-3-users. The ns-developers mailing list is friendly as well, but it assumes that you have some knowledge of ns-3, and out-of-scope posts will usually be redirected to ns-3-users.

	Please do not post the same message to both lists; pick one. ns-3 maintainers read both lists.		Please do not post the same message to both lists; pick one. ns-3 maintainers read both lists.
Line 62:		Line 62:
	=== Useful posting tips: ===		=== Useful posting tips: ===

	In order to have more ~~chanches~~ to have a fast and meaningful answer, please do the following:		In order to have more chances to have a fast and meaningful answer, please do the following:

	* Use an informative subject line (not something like `question', or 'help me').		* Use an informative subject line (not something like `question', or 'help me').
Line 101:		Line 101:
	** Check if someone else posted a reply. If the question has just arrived in your inbox, wait half an hour.		** Check if someone else posted a reply. If the question has just arrived in your inbox, wait half an hour.
	** If no one has posted a reply, then post your reply.		** If no one has posted a reply, then post your reply.
	* ~~Always consider language and cultural barriers. What is ''friendly''~~ in ~~your country may be offensive for others, or simply confusing. Moreover~~,		* Use professional writing guidelines to convey information in a clear, efficient way
	** ~~Never~~, ~~ever~~ do jokes about sex, religion, culture.		** No profanity, and never do jokes about sex, religion, culture, or about someone's misuse of the English language. You can be funny without being offensive.
			** Avoid interactions that could be considered to be harassing or mocking someone else. If you are interacting with someone who you feel is not making a fair effort to follow the list guidelines, it is best to just stop replying further, rather than to post something out of anger or frustration or to try to get the last word in.
			** Do not plead (e.g., repeatedly asking the same question or with capitalization or many exclamation points) if you do not get the answer you want as quickly as you may want it.
	* Never post something if you are angry. Wait some hours and re-read your message if you composed it while you was upset.		* Never post something if you are angry. Wait some hours and re-read your message if you composed it while you was upset.

Tomh: guidelines for posting

2015-12-08T19:49:24Z

guidelines for posting

New page

{{TOC}}

== Posting Guide: How to ask good questions that prompt useful answers ==

This guide is intended to make more productive use of the ns-3-users group by recommending best practices for posting questions and answers. Please keep in mind that over 4000 people subscribe to this group, so it is common courtesy to follow this guidance.

If one of the project maintainers responds to your question by citing this guide, please re-read the guidance before asking your question again.

This guide is freely adapted from the R Posting Guide (http://www.r-project.org/posting-guide.html)

=== The list: ===

ns-3 is open source software, constructed and maintained by volunteers. They have various reasons for contributing software and participating on the group, but often have limited time. Please help them quickly understand the details about your problem, and please avoid asking questions that have already been answered.

=== Good manners: ===

Follow etiquette and professionalism guidelines found in [https://www.ietf.org/rfc/rfc1855.txt RFC1855] and [https://www.ietf.org/rfc/rfc7704.txt RFC7704]. Please read these if you haven't already.

Customs differ. Some people are very direct. Others surround everything they say with hedges and apologies. Be tolerant. Rudeness is never warranted, but sometimes `read the manual' ''is'' the appropriate response. Don't waste time discussing such matters on the list. Ad hominem comments are absolutely out of place.

Note: if moderators find posts that lack etiquette or professionalism, we will follow an escalation path that will result in private and/or public warnings, and eventual ban from the group if behavior is not modified.

=== Questions about networking protocols: ===

The ns-3-users group primarily intended for questions and discussion about the ns-3 software. However, questions about networking protocols are sometimes posted. If the question is well-asked and of interest to someone on the list, it may elicit an informative up-to-date answer.

=== Basic networking and classroom homework: ===

The ns-3 user group is not intended for basic networking or classroom homework. Feel free to ask questions, but don't ask to help solving a class assignment (it's cheating, and your teacher will find it).

=== Announcements: ===

Job postings specific to ns-3 (e.g. postdoctoral or professional appointments related to ns-3 specifically) are allowed. General job postings unrelated to ns-3 are inappropriate.

Calls for participation in events related to ns-3 (e.g. Workshop on ns-3, or other simulation/emulation workshops where ns-3 would be considered a mainstream topic) are allowed. General conference/workshop/journal call for papers are inappropriate.

=== Which group (or mailing list)?: ===

ns-3-users or ns-developers? There are two widely used mailing lists for questions and discussion about ns-3.

* '''ns-3-users''' is intended for people who want to use ns-3 but who are not necessarily interested in developing new or extending existing modules for public release.
* '''ns-developers''' is intended for questions and discussion about code development in ns-3, new features, etc.

Questions such as "Does ns-3 support <insert-protocol-model> because I'd like to reuse it if so?" should always be asked on ns-3-users. Questions such as "Is anyone developing a model of <insert-protocol-model> for contributing back to ns-3?" are appropriate for ns-developers or ns-3-users.

New users, or users seeking help in performing a particular task are probably more confortable with ns-3-users. The ns-developers mailing list is friendly as well, but it assumes that you have a thorough knowledge of ns-3, and out-of-scope posts will usually be redirected to ns-3-users.

Please do not post the same message to both lists; pick one. ns-3 maintainers read both lists.

=== Do your homework before posting: ===

If it is clear that you have done basic background research and searched already for the answer, you are far more likely to get an informative response.

* Search the ns-3-users group. The web interface has a nice search feature, use it.
* Search the web. Use your preferred search engine, you may find good tips.
* Search the ns-3 wiki, manual and Doxygen.
* For ''any'' result found, pay attention to the post date. Some posts are about very old ns-3 versions, and the solution may not be working anymore. Or the problem may have been fixed altogether.
* When possible, always use the latest ns-3 release. If you are using an older release, please try to reproduce your problem on the most recent release or development code to see if it has already been fixed.
* If you have doubts that something changed from release to release, consult the ns-3 changes file (it is named CHANGES.html).
* If you search for help for an unsupported module (e.g., one not distributed with ns-3-allinone), contact the module developer first.

=== Useful posting tips: ===

In order to have more chanches to have a fast and meaningful answer, please do the following:

* Use an informative subject line (not something like `question', or 'help me').
* Do not ask another unrelated question by replying to an existing thread with a different subject line; start a new thread instead.
* Don't expect a reply in hours. Feel free to bump the question, but only after a couple of days.
* Only reply to ''recent'' threads (less then 1 year old).
* The more threads you ask the same question in, the ''less'' you will receive an answer.
* Do not include more than 10 lines of code in the message. The group allows attachments, use them.
* The ns-3-users group is not the best place to ask basic C++ questions.
* If relevant, state clearly the ns-3 version, compiler version, OS (type and version). If you're in doubt if it's relevant, then it is.
** the ns-3 version can be found in RELEASE_NOTES, the compiler version from ''g++ --version'' and the OS type/version from ''uname -a''
* Some consider it good manners to include a concise signature specifying your affiliation, but this is not required.

=== Surprising behavior and bugs: ===

What you think is a bug may be many other things, such as a default behavior that you do not like, a feature, an undocumented feature, or a bug in the documentation.
If you think you have found a bug, feel free to discuss about it in the ns-3-users group. In order to simplify the bug processing, please try to do the following:

* Search the ns-3 Bugzilla for similar bugs. In case, feel free to ask for the estimated resolution time.
* Debug your script. Using gdb or any debugger GUI is mandatory to discriminate between a ns-3 bug and a mistake in the user's script.
* Simplify the offending script to the bare minimum. Try to reproduce reliably the misbehaviour in the very latest ns-3 version, possibly ns-3-dev.
* When opening or replying to a bug, remember that:
*# Any bug is maximum priority for who found it, but it may not be for others. Be realistic.
*# Clearly state what was the expected behaviour and the one you got.
*# Include a script showing the bug.
*# Bugs are fixed in ns-3-dev. Make sure that your bug is present in ns-3-dev.
*# If possible, include a patch...

=== Responding to other posts: ===

* Rudeness and ad hominem comments are not acceptable. Brevity is OK.
* Take care when you quote other people's comments to respect their rights. In particular:
** Private (non-group or non-list) messages should never be quoted or forwarded to a list without the author's permission. Don't assume "it is OK"-- always ask first.
** The original authorship and meaning should always be clear.
* It is common practice to quote prior messages in entirety.
* If you edit the quoted text from prior messages, include sufficient context so that the content is clear even if your archived message is referenced at a much later date and in isolation from other messages.
* When responding to a very simple question, use the following algorithm:
** Check if someone else posted a reply. If the question has just arrived in your inbox, wait half an hour.
** If no one has posted a reply, then post your reply.
* Always consider language and cultural barriers. What is ''friendly'' in your country may be offensive for others, or simply confusing. Moreover,
** Never, ever do jokes about sex, religion, culture.
* Never post something if you are angry. Wait some hours and re-read your message if you composed it while you was upset.

=== Common posting mistakes: ===

* Missing or non-specific message subject
* Not doing basic homework before posting a question
* Not being more specific than `function xxx doesn't work'
* Being overly specific and not stating your real goal; there may be another solution if your underlying goal is better understood
* Not including version and OS information in question regarding unexpected behavior.
* Finding a bug in an old version of ns-3 that has been fixed in the most recent version.
* Claiming that something is a bug when in fact the software is working as intended and documented, just not in the way you first expected.
* Threatening not to use the software if you cannot get your question answered. Even when intended as a statement of fact, this tends to create negative attitudes.
* Posting the same question more than once per day (in different threads).

=== Final words: ===

It is a skill to ask good questions. If at first you don't get the answers that are useful to you, don't get discouraged. A response that is concise and technically accurate may be just that, and not an intended putdown. If you feel insulted by some response to a post of yours, don't make any hasty response in return - you're more likely than not to regret it. Read Eric Raymond's essay [http://www.catb.org/esr/faqs/smart-questions.html How To Ask Questions The Smart Way] for more suggestions, and for insight into people's behavior on technical mailing lists.

Posters should be aware that the ns-3 lists are public discussion lists and anything you post will be archived and accessible via several websites for many years, and we cannot remove any posts (it is a Google service).