Enhanced comment feature has been enabled for all readers including those not logged in. Click on the Discussion tab (top left) to add or reply to discussions.

Authors' Resources: Difference between revisions

From BIF Guidelines Wiki
No edit summary
No edit summary
 
(16 intermediate revisions by 2 users not shown)
Line 1: Line 1:
THIS PAGE IS UNDER CONSTRUCTION
The BIF Guidelines Drafting Committee was initially selected by the BIF Board of Directors in June of 2018, and given the mandate to redevelop the BIF Guidelines for Uniform Beef Improvement as a wiki. Six members with a diverse set of experiences and knowledge were chosen to reorganize and refresh the BIF Guidelines book.  Much in beef cattle improvement had changed since the last edition (9th). Technologies were rapidly advancing and it was recognized that accessing a larger community of stakeholders and experts would be more effective at keeping the Guidelines current. It had become clear to the board that a wiki format managed by the Drafting Committee, with oversite from the Board's Guidelines Committee, and developed by the stakeholders, met these needs.  The wiki markdown environment simplifies authoring content while providing powerful modern web capabilities.


Below are notes, guidance and links to resources for authors of these wiki pages.  If you have been asked to author a page in this wiki please check back here regularly as this content may have been updated.
Below are notes, guidance and links to resources for authors of these wiki pages.  If you have been asked to author a page in this wiki please check back here regularly as this content may have been updated.


=How Authors are Chosen=
=How Authors are Chosen=
The BIF Guidelines Drafting Committee was initially selected by the BIF Board of Directors in June of 2018, and given the mandate to redevelop the BIF Guidelines for Uniform Beef Improvement as a wiki. Eight members with a diverse set of experiences and knowledge were chosen to reorganize and refresh the previous BIF Guidelines which was a book.  Much in beef cattle improvement had changed since the last edition (9th). Technologies were rapidly advancing and the effort required for keeping the Guidelines current would require regular contributions from the larger community of stakeholders and experts. It had become clear to the board that a wiki format managed by the Drafting Committee and developed by the stakeholders, met these needs.  The wiki markdown environment simplifies authoring content while providing powerful modern web capabilities.


While the [https://www.mediawiki.org/wiki/Best_practices_for_using_MediaWiki best practices of wiki development] include initially not over organizing content, some initial structure and principles were required that authors can follow.  The information in this page reflects the Drafting Committee's specifications. This wiki is initially organized into six general topic areas that appear on the menu at the bottom of the [[Main_Page]].  Each topic area is managed by a Content Coordinator who is a member of the BIF Guidelines Drafting Committee.  Content in this wiki is dynamic and evolving. As a Content Coordinator identifies a topic that needs to be developed or updated, that coordinator will contact a stakeholder and request that a draft of the content is added to the wiki. Because only logged in users can add and modify content, the Content Coordinator will provide new authors with login credentials.


If any stakeholder would like to become an author, please contact the Head Content Coordinator of the Guidelines Drafting Committee or the appropriate Content Coordinator to make a request.  Please include your proposed topic and relevant experience.  You can find the list of Content Coordinators on the [[BIF Guidelines Drafting Committee]] page.
While the [https://www.mediawiki.org/wiki/Best_practices_for_using_MediaWiki best practices of wiki development] include initially not over organizing content, some initial structure and principles were required for authors to follow.  The information in this page reflects the Drafting Committee's specifications. This wiki is organized into general topic areas that appear on the blue menu at the top of the [[Guidelines_for_Uniform_Beef_Improvement_Programs]].  Each topic area is managed by a Content Coordinator who is a member of the BIF Guidelines Drafting Committee.  Content in this wiki is dynamic and evolving. As a Content Coordinator identifies a topic that needs to be developed or updated, that coordinator will contact a stakeholder-author and request that a draft of the new content is added to the wiki. Because only logged in users can add and modify content, the Content Coordinator will provide new authors with login credentials.
 
If any stakeholder would like to become an author, please contact the Lead Content Coordinator or the subject area Content Coordinator of the Guidelines Drafting Committee to make a request.  Please include your proposed topic, relevant experience and the subject area where you propose the content be included.  You can find the list of Content Coordinators on the [[BIF Guidelines Drafting Committee]] page.


= General Guidance =
= General Guidance =
*Authors should review the information on this page prior to contributing.
*Authors should review the information on this page prior to contributing.
*Authors who are new to creating wiki content and are unfamiliar with [https://en.wikipedia.org/wiki/Markdown  wiki markdown] should spend some time experimenting with the http://protobifgl.thetasolutionsllc.com page.  This prototyping version of the wiki will never go live and is provided to test ideas.  Put or modify anything you want in this prototyping area.  Be aware that the prototype is not backed-up and it will be refreshed regularly so what you put into the prototype will disappear. See the resource links below for information on [https://en.wikipedia.org/wiki/Markdown wiki markdown].


*If you do inadvertently corrupt anything in the production wiki do not worry.  Any modifications can be [https://en.wikipedia.org/wiki/Help:Reverting reverted to a previous version].  If you are uncomfortable with reverting something please contact your Content Coordinator for assistance.
*If you do inadvertently corrupt anything in the production wiki do not worry.  Any modifications can be [https://en.wikipedia.org/wiki/Help:Reverting reverted to a previous version].  If you are uncomfortable with reverting something please contact your Content Coordinator for assistance.
Line 21: Line 19:
*Avoid standard abbreviations such as d for day, y for year, bw for body weight.  Acronyms should be avoided except when the acronym is part of the regularly used term of the art (e.g., ERT for "economically relevant trait"). When an acronym or term of the art is used it should be defined on first use and an entry should be made in the  [[Glossary]].
*Avoid standard abbreviations such as d for day, y for year, bw for body weight.  Acronyms should be avoided except when the acronym is part of the regularly used term of the art (e.g., ERT for "economically relevant trait"). When an acronym or term of the art is used it should be defined on first use and an entry should be made in the  [[Glossary]].


* Authors should be aware that their content may have a degree of overlap to other [[Main_Page | Main Page content]] areas and should work with their Drafting Committee Content Coordinator (the Committee member who contacted you) to coordinate with the Drafting Committee Content Coordinator of overlapping content areas.  For example, if writing about Total Herd Reporting, authors should be aware that this will impact at least three other areas of [[Main Page]] sub-content.
* Authors should be aware that their content may have a degree of overlap to other [[Guidelines_for_Uniform_Beef_Improvement_Programs]] areas and should work with their Drafting Committee Content Coordinator (the Committee member who contacted you) to coordinate with the Drafting Committee Content Coordinator of overlapping content areas.  For example, if writing about Total Herd Reporting, authors should be aware that this will impact at least three other areas of [[Guidelines for Uniform Beef Improvement Programs]] sub-content.


*Authors should be aware of pages in this wiki that have covered details about a point they are covering.  For example, If an author were discussing age-of-dam adjustments on a particular trait they were discussing, a link to the [[Age of Dam | general discussion of age-of-dam]] should be made.  Using the search area at the top of each page or the [[Special:Search | search special page]] will facilitate finding places to make these links.
*Authors should be aware of articles in this wiki that have covered details about a point they are covering.  For example, If an author were discussing age-of-dam adjustments on a particular trait they were discussing, a link to the [[Age of Dam | general discussion of age-of-dam]] should be made.  Using the search area at the top of each article or the [[Special:Search | search special page]] will facilitate finding places to make these links.


*http://Gramerly.com provides a powerful free plugin for browsers that checks spelling, grammar and punctuation on the fly as it is typed.  Authors are strongly encouraged to install this easy to use plugin.
*http://Gramerly.com provides a powerful free plugin for browsers that checks spelling, grammar and punctuation on the fly as it is typed.  Authors are strongly encouraged to install this easy to use plugin.
Line 29: Line 27:
*The MediaWiki basic markdown and editing environment are very easy to use.  However, as with any software, the more powerful capability can be tapped with just a little effort.  In order to develop the wiki capabilities of the stakeholder community, authors are encouraged to perform all their editing in the wiki.  However, if absolutely necessary, while adding to the effort and burden of the Content Coordinator, authors may develop content in familiar editors such as MSWord and email it to the Content Coordinator.  But please consider that everyone here is a volunteer doing this work for the greater good.
*The MediaWiki basic markdown and editing environment are very easy to use.  However, as with any software, the more powerful capability can be tapped with just a little effort.  In order to develop the wiki capabilities of the stakeholder community, authors are encouraged to perform all their editing in the wiki.  However, if absolutely necessary, while adding to the effort and burden of the Content Coordinator, authors may develop content in familiar editors such as MSWord and email it to the Content Coordinator.  But please consider that everyone here is a volunteer doing this work for the greater good.


*The MediaWiki software we are using is very powerful and will track authors' contributions.  All new pages and edits are recorded and the attribution to the author can be seen by going to the History tab on each page.  Additionally, the bottom of each page indicates the original author and the most recent changes.  If an author includes content that is not original then citation must be made to the original work using the [https://www.mediawiki.org/wiki/Help:Cite ref cite tags].
*The MediaWiki software we are using is very powerful and will track authors' contributions.  All new articles and edits are recorded and the attribution to the author can be seen by going to the History tab on each article.  Additionally, the bottom of each article indicates the original author and the most recent changes.   
 
* If an author includes content that is not original then citation must be made to the original work using the [https://www.mediawiki.org/wiki/Help:Cite ref cite tags].
 
*Generally, articles should be kept to a minimum of one to two screens. Longer articles may be necessary but authors should consider breaking a longer article into logical multiple linked articles.  Generally, it is best practice to organize articles in a hierarchy.  The top article is the high-level explanation of the concept and the detail is on separate articles that are linked to the top article.
 
*Often articles can be shortened if, for example, larger tables or large images are placed on a stand-alone page with a link from the article.
 
* Use [https://academic.oup.com/jas/pages/General_Instructions Journal of Animal Science format] for references.
 
= Draft Article Approval=
The need for a specific article (wiki page) is usually identified by a subject area [[BIF Guidelines Drafting Committee | Content Coordinator]].  The Content Coordinator will contact an appropriate member from the stakeholder community to request that the article be drafted. If the stakeholder-author agrees to develop the draft and can accomplish it within two weeks, the author will be given a user account on the Guidelines production wiki. Before writing, authors should review the material in this article and familiarize themselves with basics of markdown.
 
Once drafted, the author contacts the Content Coordinator, who reviews the draft.  The Content Coordinator and Editor may also perform editing on the draft.  The Content Coordinator then approves the article (using MediaWiki's approval feature). 
 
Articles should be considered to be constantly evolving.  Any member of the approved authors' community will be allowed to make changes to any of the Guidelines wiki articles.  However, only Content Coordinators can approve changes.  Changes made to an article may be reverted if the Content Coordinator does not approve.  If an author wishes to make major changes to an existing article, the author should first contact the Content Coordinator and discuss the revision.
 
Any member of the stakeholder community may request authoring a content article by contacting the appropriate Content Coordinator.
 
= Trait Articles =
Authors asked to write each trait's article are provided a template to use for developing the article.  It contains a standard set of sub-section headings and guidance.  Click on [[Trait Template | this link]] to go to instructions on how to use the trait template 


= Links to Resources =
= Links to Resources =
'''Editing'''<br>
http://gramerly.com
http://gramerly.com


https://academic.oup.com/jas/pages/General_Instructions
'''Markdown'''<br>
https://en.wikipedia.org/wiki/Markdown
https://en.wikipedia.org/wiki/Markdown


Line 40: Line 62:
https://www.tablesgenerator.com/mediawiki_tables
https://www.tablesgenerator.com/mediawiki_tables


'''Best Practices'''<br>
https://www.mediawiki.org/wiki/Best_practices_for_using_MediaWiki
https://www.mediawiki.org/wiki/Best_practices_for_using_MediaWiki
https://www.quora.com/What-are-some-best-practices-for-running-an-internal-Wiki

Latest revision as of 21:00, 13 April 2021

The BIF Guidelines Drafting Committee was initially selected by the BIF Board of Directors in June of 2018, and given the mandate to redevelop the BIF Guidelines for Uniform Beef Improvement as a wiki. Six members with a diverse set of experiences and knowledge were chosen to reorganize and refresh the BIF Guidelines book. Much in beef cattle improvement had changed since the last edition (9th). Technologies were rapidly advancing and it was recognized that accessing a larger community of stakeholders and experts would be more effective at keeping the Guidelines current. It had become clear to the board that a wiki format managed by the Drafting Committee, with oversite from the Board's Guidelines Committee, and developed by the stakeholders, met these needs. The wiki markdown environment simplifies authoring content while providing powerful modern web capabilities.

Below are notes, guidance and links to resources for authors of these wiki pages. If you have been asked to author a page in this wiki please check back here regularly as this content may have been updated.

How Authors are Chosen

While the best practices of wiki development include initially not over organizing content, some initial structure and principles were required for authors to follow. The information in this page reflects the Drafting Committee's specifications. This wiki is organized into general topic areas that appear on the blue menu at the top of the Guidelines_for_Uniform_Beef_Improvement_Programs. Each topic area is managed by a Content Coordinator who is a member of the BIF Guidelines Drafting Committee. Content in this wiki is dynamic and evolving. As a Content Coordinator identifies a topic that needs to be developed or updated, that coordinator will contact a stakeholder-author and request that a draft of the new content is added to the wiki. Because only logged in users can add and modify content, the Content Coordinator will provide new authors with login credentials.

If any stakeholder would like to become an author, please contact the Lead Content Coordinator or the subject area Content Coordinator of the Guidelines Drafting Committee to make a request. Please include your proposed topic, relevant experience and the subject area where you propose the content be included. You can find the list of Content Coordinators on the BIF Guidelines Drafting Committee page.

General Guidance

  • Authors should review the information on this page prior to contributing.
  • If you do inadvertently corrupt anything in the production wiki do not worry. Any modifications can be reverted to a previous version. If you are uncomfortable with reverting something please contact your Content Coordinator for assistance.
  • Avoid standard abbreviations such as d for day, y for year, bw for body weight. Acronyms should be avoided except when the acronym is part of the regularly used term of the art (e.g., ERT for "economically relevant trait"). When an acronym or term of the art is used it should be defined on first use and an entry should be made in the Glossary.
  • Authors should be aware that their content may have a degree of overlap to other Guidelines_for_Uniform_Beef_Improvement_Programs areas and should work with their Drafting Committee Content Coordinator (the Committee member who contacted you) to coordinate with the Drafting Committee Content Coordinator of overlapping content areas. For example, if writing about Total Herd Reporting, authors should be aware that this will impact at least three other areas of Guidelines for Uniform Beef Improvement Programs sub-content.
  • Authors should be aware of articles in this wiki that have covered details about a point they are covering. For example, If an author were discussing age-of-dam adjustments on a particular trait they were discussing, a link to the general discussion of age-of-dam should be made. Using the search area at the top of each article or the search special page will facilitate finding places to make these links.
  • http://Gramerly.com provides a powerful free plugin for browsers that checks spelling, grammar and punctuation on the fly as it is typed. Authors are strongly encouraged to install this easy to use plugin.
  • The MediaWiki basic markdown and editing environment are very easy to use. However, as with any software, the more powerful capability can be tapped with just a little effort. In order to develop the wiki capabilities of the stakeholder community, authors are encouraged to perform all their editing in the wiki. However, if absolutely necessary, while adding to the effort and burden of the Content Coordinator, authors may develop content in familiar editors such as MSWord and email it to the Content Coordinator. But please consider that everyone here is a volunteer doing this work for the greater good.
  • The MediaWiki software we are using is very powerful and will track authors' contributions. All new articles and edits are recorded and the attribution to the author can be seen by going to the History tab on each article. Additionally, the bottom of each article indicates the original author and the most recent changes.
  • If an author includes content that is not original then citation must be made to the original work using the ref cite tags.
  • Generally, articles should be kept to a minimum of one to two screens. Longer articles may be necessary but authors should consider breaking a longer article into logical multiple linked articles. Generally, it is best practice to organize articles in a hierarchy. The top article is the high-level explanation of the concept and the detail is on separate articles that are linked to the top article.
  • Often articles can be shortened if, for example, larger tables or large images are placed on a stand-alone page with a link from the article.

Draft Article Approval

The need for a specific article (wiki page) is usually identified by a subject area Content Coordinator. The Content Coordinator will contact an appropriate member from the stakeholder community to request that the article be drafted. If the stakeholder-author agrees to develop the draft and can accomplish it within two weeks, the author will be given a user account on the Guidelines production wiki. Before writing, authors should review the material in this article and familiarize themselves with basics of markdown.

Once drafted, the author contacts the Content Coordinator, who reviews the draft. The Content Coordinator and Editor may also perform editing on the draft. The Content Coordinator then approves the article (using MediaWiki's approval feature).

Articles should be considered to be constantly evolving. Any member of the approved authors' community will be allowed to make changes to any of the Guidelines wiki articles. However, only Content Coordinators can approve changes. Changes made to an article may be reverted if the Content Coordinator does not approve. If an author wishes to make major changes to an existing article, the author should first contact the Content Coordinator and discuss the revision.

Any member of the stakeholder community may request authoring a content article by contacting the appropriate Content Coordinator.

Trait Articles

Authors asked to write each trait's article are provided a template to use for developing the article. It contains a standard set of sub-section headings and guidance. Click on this link to go to instructions on how to use the trait template

Links to Resources

Editing
http://gramerly.com

https://academic.oup.com/jas/pages/General_Instructions

Markdown
https://en.wikipedia.org/wiki/Markdown

https://en.wikipedia.org/wiki/Help:Cheatsheet

https://www.tablesgenerator.com/mediawiki_tables

Best Practices
https://www.mediawiki.org/wiki/Best_practices_for_using_MediaWiki

https://www.quora.com/What-are-some-best-practices-for-running-an-internal-Wiki