Sample Article Structure

Article Synopsis

---

Be sure to start your article with a brief statement of what it is. Obvious, right? But it will save readers a lot of time when searching for something. For example, the purpose of this document is to provide a guideline and suggestions as to how an article in MRT SIG Wiki should be structured and written. And steps on how it should be reviewed before publishing it.

This is a new or updated article by Don (DErik (talk)) Erikstrup being reviewed

The C4 of Writing

Guidelines on how to write the article are of course extremely subjective. But for the most part, the following should be attempted:

• Be concise: discuss only the main issues of the article as a whole, being more focused in each chapter or subchapter. If there are related topics and articles, put a reference to them rather than talking about them here. Of course, there is a caveat to that as well: If trompping off to some other web page, or a book, is time-consuming or distracting, but the information is helpful to understand this article, then inclusion here might be better. It must be balanced with being clear (next bullet).
• Be clear: don't use words or acronyms without explaning them. Include references to other web pages, books, people, what or who ever to ensure that your descriptions and explanations are understood. This must be balanced with being concise (previous bullet).
• Be complete: cover all the relevant issues regarding this topic, but don't get too verbose. Include pictures/videos. But remember to be consise.
• Be correct: I know you are, but check your work for typos, grammatical errors, links to other references that don't work, missing references and links.

Put Chapters In It

Your article may describe a particular product. Or provide the steps in performing a specific task. Or provide an explanation of something. The following provides suggested "chapter" headings, with a brief description of what should be included.

The structure of the article may change based on its purpose. For example, an explanation of something may not require any sectioning as done below, but instead may require sections to describe alternatives or substitutions. And subheadings are going to be needed in most of the articles. So feel free to use as many sub-chapter headings as needed.

Note the Table Of Contents on this page, up and to the right. It is probably a good thing to include. To do that, just include a line at the very top of your article like this:
{{rtoc}}
Note that it must be to the far left of the line.

Product or Item Description

This may be all that is needed for a particular item. But there may be other products that are similar or related to this product. Put references in here to those. If what you are writing is a "how-to", then this should describe the end result, to include its physical appearance and expected usage and function.

Materials Needed

For performing a task, such as building a house, laying out track, putting features (ponds, roads, forests, people) in the layout, creating control items (switches, RR crossing gates, sensors to light buildings or active other things). List the materials, and the tools. Provide alternatives if possible and appropriate.

It would also be useful to list the sources of the materials.

Product Building Steps

List the steps needed to perform the task in a logical manner. Ya, I know you will. This is pretty obvious.

● Bullet list of steps for actions that can be done in any order.

1. Numbered steps for actions that must be done in a specific order.

Include pictures and videos where possible and appropriate.

Uses and Alternatives

Describe where the product or item might be used and what alternatives there are to using it. You might include a list of pros and cons to using the product or its alternatives.

Cautions

Identify uses to which the product should NOT be applied. Identify things that should be done, or not, to protect or preserve the product. Identify things that should be done when making or using the product, or materials used in making the end product, such as environmental conditions (eg., use a fan, do it outdoors, wear mask or googles) or special materials to use or avoid (eg., certain filaments or resins for specific 3D printers).

Categorize Your Article

It is also a good idea, in fact, a requirement, to include your article in one or more categories of related articles. As you may note in the "MRT SIG Topics" page, we have suggested several different categories for various articles. These categories are by no means the be-all and end-all. If you have another category in mind, please suggest it.

If you believe your article belongs in one of the categories, or even some other category, include it there by adding the following line

[[Category:whatever category you want]]

somewhere (perferably the top or bottom of your page). (Note: It should be on a line all by itself, left justified.) The category you supply need not even exist. That's OK too. But if you do, please inform us of it, and provide a brief description of what would typically be included in that category. It will then be added to the topics page.

Publication Work Flow

The following may seem a bit too much for just publishing a simple article here. But be aware that EVERYONE IN THE WORLD will be able to see these pages. So we want them to be as useful, informative, and of the best quality possible.

The steps that should be taken to publish an article here should be the following. At present, we are not enforcing this either, and frankly, I'm not sure that we can. But good etiquette and practices should indicate the need for these steps.

1. You first create a draft of the article. You can use whatever medium you desire and feel comfortable with. For example:
   • Simple paper and pencil (and maybe some crayons) would work to create the first draft.
   • Or you could use Apple's "Text Editor" or Microsoft's "Notepad" applications. These produce text (.TXT) files with no formatting capabilities. Very simple and easy to use.
   • Or step up a bit to use "Notepad++", a free download, but it only works on Windows platforms. But it understands things like programming languages (Java, C++, C#, Python, PHP, others) and markup languages (HTML, CSS, XML, even TeX which is used for math equations, but it doesn't understand Wiki markups 🥲). It will save files in with an extension compatible to the type of file it thinks it is. But they are all essentially straight text files. There is no formatting capability saved with the file.
   • To save a bit of formatting you could then step up to using:
     • Apple's Pages (creates a .PAGES file, but can be exported to PDF, Word DOCX, Rich Text Format (.RTF file), and a few others).
     • Or MS's Word (DOCX for latest version of Word, also exports as PDF, DOC, ODT, RTF, MHT, MHTML, others). The MHT and MHTML are somewhat equivalent to HTML or HTM pages, which are what are normally stored on web servers and what you see in the browsers.
     • Another option is using LibreOffice, a free download that has capabilities for formatting similar to MS Word. The default file type is ODT (see the MS Word export types), which is similar to a DOC or DOCX file. It can also save files in XML, HTML, RTF, and a few variations of MS Word formats. And it runs on either Apple OS or Windows.
       (Note: I'm not advocating or advertising for LibreOffice. But I do find it useful for cross-platform editing.)
   • You could also use spreadsheet applications, like Excel (.XLS or .XLSX files), or Apple's Numbers (.NUMBERS files), or LibreOffice to generate MS Excel type files with default extension of .ODS.
   • And presentation applications, like Apple's Keynote (for .KEY files) or MS PowerPoint (for .PPTX files) or LibreOffice (for .ODP files).
   • Or you could use the MediaWiki itself. Just create a new page (with a name you would like to use for the article) and go for it.
2. When you create the new page, the first thing you should do is include the line

   [[Category:Works In Progress]] <span style="color:red;"><br>Under construction/modification by ~~~~<br></span>

   at the top of your article, just after the synopsis. This puts the article in that category so the MRT SIG, and others, know that the page is not yet complete. You will see that it adds a reference to the bottom of the page indicating its inclusion in that category. You can click on the category to see additional notes and instructions on how the article creation process should work, as well as getting a list of other articles currently in progress. You may find one similar to your own. Then be sure to copy&paste from whatever application you used to draft the article to the wiki page, and make additional adjustments as needed.
3. When you feel you are done and are happy with the draft, be sure to "Save changes...". Then edit that page to alter the inclusion of the article in the Category:Works In Progress to be

   [[Category:Pending Review]] <span style="color:red;"><br>New or modified article by ~~~ being reviewed<br></span>

   category. This lets the MRT SIG, and others, know the article is essentially complete. However, the MRT SIG folks would first like to review the article. This is requested so that a second set of eyes can review it for clarity, understandability, completeness, and such things. Think of it as submitting an article to a publisher or newspaper. They always review it for content conformance, suitability to their policies, grammar and vocabulary, and other things. We would like to do that as well, just to make sure we are publishing the best possible articles we can. Know that these articles are viewable by EVERYONE IN THE WORLD. So we need to do the best we can.
4. When the article has had a review, and additional changes are requested or needed, the article will be returned to the Category:Works In Progress category. If no further changes are needed, the page will be removed from the Category:Pending Review category.
5. Finally, if it hasn't already been done, the article will be included in the various categories it should belong to. (See the MRT SIG Topics page for existing and recommended topics, but feel free to create your own. Just let the MRT SIG know, and provide a brief description of the category so others will know what to expect or include in it.) This will allow it to be easily found by one and all.

Conformance and Consistency

To attempt to make these pages as understandable and usable as possible, we have created a "Sample Article Structure" page that suggests what needs to be included in a page and how to arrange it. We aren't [yet] enforcing this, as we are just getting started and we want feedback on this. So take a look at it and let us know if it meets your needs. And if not, how to improve it.

References and Additional Info

There is a way to create a list of references made throughout your article and have it presented here. See the Wiki Usage and Editing page for an explanation of how to do this.

You might also want to include additional references here. A bulletized list would be a good way to do this, with a section heading of "See Also" perhaps.

See Also

• Wiki Usage and Editing: This will provide you with a few tips and tricks, and perhaps even some essential knowledge on the mechanics of putting an article into this wiki. If you don't understand, though, please don't be afraid to ask for help. You have no idea how much I still don't know and am asking others for help.

Authors and Contributors

And you might want to include the names and contact information of the author(s) and contributors to this article. Another bulletized list with a section heading of "Authors and Contributors" would be appropriate.

---

• Don Erikstrup - Please use the discussion tab above to leave me a note or comment. Or leave a coment at DErik's talk page.