FlightGear wiki talk:Manual of Style

Some suggested changes

Have read through FlightGear wiki:Manual of Style#Article titles, headings, and sections (perm) and have the following suggestions:

Section	Suggested changes	Comments from other users
Section organization (perm)	lead section → first section a navigable table of contents → a table of contents with links to the sections The section could mention a bit less about formatting
Section headings (perm)	Spaces between the equal signs and the heading text are optional → Spaces between the equal signs and the heading text are recommended but optional

Will read some more further on.

—Johan G (Talk | contribs) 21:02, 17 August 2014 (UTC)

"FlightGear wiki:Style guide" should be merged here

FlightGear wiki:Style guide never got completed and predates FlightGear wiki:Manual of Style, that have replace it and should be used instead.

The little that could should probably be merged into the style manual. After that the style guide could be deleted as it never got completed.

—Johan G (Talk | contribs) 11:20, 4 August 2015 (EDT)

Done - the only page which still needs to be merged is FlightGear wiki:Style guide – Article disposition. Do you think its contents can be inserted here "as they are", in a dedicated subsection, or would that recommendation benefit from an expansion (for example, by creating different templates for different page types - one for aircraft, another one for airports, and so on)?

-- ElGaton (talk to me) 12:20, 8 April 2016 (EDT)

A big "Thank you!" to you (and Red Leader) for that work. :-D

Regarding article disposition, it is more of a gudeline than a rule, but for the sake of consistency (and readability/navigability at large) I think the wiki could use a more common layout. The aircraft and airport articles are a bit special in that they handle content that is very similar from article to article, so I think it would be even greater for those. (Have you ever looked for something, only to find it later because it was out of place? ;-).

I wonder what the more common aircraft and airport article dispositions currently look like and what the differences, pros and cons with them are.

—Johan G (Talk | contribs) 02:01, 12 April 2016 (EDT)

I'll have a look at this in the next days.

-- ElGaton (talk to me) 08:03, 14 April 2016 (EDT)

External links

I think this section needs improvement as this article clearly breaks its own rules. It also needs clarity as to how to reference the external links within the main text. Maybe this should be shifted to be a recommendation, rather than a hard rule, as not many pages on the FlightGear wiki appear to follow this rule. Bugman (talk) 11:12, 22 September 2015 (EDT)

I think the external links in that section serves as examples on how the links would render. They simply need to be there.

Regarding clarity, could you elaborate on what you miss regarding to referencing the external links. Are you thinking purely about using <ref/> tags, or are you thinking in broader terms?

It seems that very few pages fully follow the style manual. :-\ I often feel an urge to add a page listing pages one can assume are the most visited, list all the style issues, and slowly work my way through them. That might also help get more editors interested.

—Johan G (Talk | contribs) 03:33, 25 September 2015 (EDT)

The key rule "Do not use external links in the body of an article" is difficult and sometimes impossible to adhere to. This strict rule implies never using [URL text] markup and only using <ref/> tags. Wikipedia, for example, now uses a self-written Mediawiki extension which causes pop ups to appear when the mouse hovers over the rendered <ref/> tags, so that you do not need to jump to the bottom of the page to open an external link in a new tab/window. If the rule is strictly followed, then chasing down external links results in a quite discontinuous reading of the article, requiring you to jump to then end of the article, open the external link, and then jump back to where you were. This is very unpleasant for large articles (in the FGAddon article I am working on, for example). I assume that that is why almost all FG wiki articles do not or cannot follow this rule, and why this rule is consistently broken including in the FlightGear wiki:Manual of Style article itself. There are also articles types which, by nature, should not follow this rule (Flightgear_hangars and Links for example).

Bugman (talk) 04:13, 25 September 2015 (EDT)

I sort of agree with Bugman: it might make more sense to use a criterion similar to the one employed for internal links, that is, keeping external links in the body only if a) they are relevant in the context and b) it is expected that the user will (almost) always follow them when reading the text or are otherwise deemed always essential to comprehend the text. Referring to the FGAddon article he mentioned, most external links in it would fall into this category, for example the ones in the Preparation section and aircraft hangar links, which are expected to be followed by the user, or the inline link to the policy document. Other ones (e.g. the ones about "preserving a linear repository history", or the svn import documentation - notions that could be intuitive and/or familiar to an experienced developer) could be easily replaced by references. The key is to avoid inline external links where they are not "strictly necessary". Also, installing the Reference Tooltips gadget he mentioned would be a nice addition to the wiki.

-- ElGaton (talk to me) 15:05, 8 April 2016 (EDT)

Abbreviations and capitals

The section Write out both the full version and the abbreviation at first occurrence is incoherent: the first bullet point appears to imply that abbreviations should be written with initial capitals, while the second one states the contrary. I guess only the second point is correct? -- ElGaton (talk to me) 13:12, 10 April 2016 (EDT)

Yes, the first example is incorrect. Feel free to change it; maybe it's even better to give both bullet points a different example (so not ILS twice) :-)

Gijs (talk) 14:32, 10 April 2016 (EDT)

Done -- ElGaton (talk to me) 15:43, 10 April 2016 (EDT)

Conventions for references, step-by-step instructions, interface elements, common templates

I have noticed that the following areas are not fully uniform throughout the wiki and might benefit from some additional guidelines. Here are my proposals - feedback is welcome:

• References: the <references /> tag (list of references) is sometimes put in a box (see e.g. Cessna 172P), sometimes in a separate section (see e.g. Taxiway signs). I'm uncertain on this point - what is the best choice?
• Step-by-step instructions: should they be written as numbered lists or in a discursive way?
• Menus/buttons/interface elements: is it reasonable to ask that buttons/menus that must be chosen be written in bold (e.g. click on OK, or choose File -> Quit)?
• Checklist steps: might they benefit from a common template?
• The manual of style should mention common templates (e.g. repository/infrastructure links, or the key press one) and encourage the user to search for existing templates and use them where available.

-- ElGaton (talk to me) 18:44, 30 April 2016 (EDT)

Ongoing I've added a standard way to include references (diff) and mentioned to use templates whenever possible (diff). Might it perhaps make sense to add some example galleries like these ones? -- ElGaton (talk to me) 15:00, 6 May 2016 (EDT)

Article subpages

Should subpages of an article (e.g. the OpenRadar or Extra500 subpages) be created hierarchically at a level below the main article (Main article/Subpage) or at the same level as the main article (Main article - Subpage)? -- ElGaton (talk to me) 18:44, 30 April 2016 (EDT)