Wikiversity talk:Manual of Style

See the /Archive 1 for older discussions.

Level 1 Headings

“ TL;DR note: The use of some wiki markup causes serious problem for navigation and usability of our site. Level 1 headers should be avoided in all but the most unusual cases. Wiki markup should not be used in section headers at all. If someone has a perceived need for using these, please ask for advice, as there as other methods that can accomplish the same goals without breaking critical features of the MediaWiki software. --mikeu ^talk 08:26, 31 January 2016 (UTC) ”

The Manual of Style indicates that Level 1 headings, a single equal sign such as = heading =, should only be used in special cases where warranted. There's more to the story than just style, however. When we enter equal signs on a heading in wikitext, the Mediawiki software coverts those into HTML heading tags, such as <H1>, <H2>, etc..

From an appearance standpoint, changing the heading level appears to change the size of the font, and article writers will often experiment with different heading levels to change the font size. This may have the desired effect on their individual platform (a particular browser on a particular operating system), but may have very different, and perhaps unintended consequences on another platform, such as mobile.

But it goes even further. From an HTML design standpoint, heading levels are also used for navigation. One example of this is the table of contents that appears automatically at the top of most pages allowing on-page navigation directly to that heading. Mediawiki software is written to handle Level 1 headings correctly in terms of page outlining, so that people with standard vision will see the page correctly, just with bigger headings.

But there is a group of users for whom Level 1 headings may have a negative impact. Users with impaired vision use screen reading software to help them navigate websites. That screen reading software is thrown off by multiple Level 1 headings. Accessibility guidelines call for only one Level 1 heading per page, and the Mediawiki software creates that level automatically with the page title. That's why all page headings are supposed to start with Level 2, == heading ==.

Based on a recent discussion where a user changed Level 1 headings to Level 2, and the change was reverted, I asked MaintenanceBot to search through the alphabetic page library (Aa - Zz only, so far), and tag pages that were using Level 1 headings so that we could examine the scope of Level 1 heading usage and discuss how we want to proceed. The result is Category:Pages with Level 1 heading, currently with about 2,500 pages identified.

I can't say how many users we might have who are impacted by this issue. I personally only know two individuals who use screen reading software in order to function, so we may be looking at a 1 in a thousand type of ratio. On the other hand, I wouldn't want our page layout to present a barrier to someone seeking knowledge. So, if there's an easy fix, I'd like to implement it so that we can try to make our content accessible to all.

I believe it would be possible to write a bot that would look at page headings, and if there is a Level 1 heading, increase the heading level by one for all headings on the page. The up side to having a bot do the work is that we can fix all of the pages in a day. The down side to having a bot do the work is that an automatic fix only works based on an assumption of heading consistency throughout the page rather than reviewing the content and finding that just one heading was created at the wrong level in error.

So, how would the community like to proceed? Do we want to fix pages automatically? Do we want to correct them manually? Do we want to create a list of pages that can be fixed automatically based on a manual review? Or do we want to just ignore the issue altogether?

Dave Braunschweig (discuss • contribs) 14:31, 30 January 2016 (UTC)

@Dave Braunschweig: This is important and we should fix it for the sake of accessibility and conformance to standards. If authors want large text for some reason, that's why we have CSS. —Justin (koavf)❤T☮C☺M☯ 15:09, 30 January 2016 (UTC)

strong support I agree that we should use strict section heading guidelines. If a contributor is unsatisfied with the appearance of a page then we should educate them about the appropriate wiki syntax to achieve the desired outcome. It is critical that our site not discriminate against people with disabilities, but there are much broader issues. I recently saw a graph that showed that desktop usage of Wikipedia has been flat in recent years, and much of the growth in visitors to the site since 2011 is mobile browsing. Mobile viewing currently accounts for 45% of traffic to Wikimedia projects overall. While I haven't seen much mobile editing[1] on wv I suspect that mobile viewing of our pages is quite high and significant. I've recently been proofreading our resources on mobile and there are some serious problems with templates and section headers that "break" usability. I've been planning to start a page to list templates in need of update and other problems that I've noticed. It will be problematic to clean up after a bot. Looking at About learning a report by Demos study group It is unclear to me what was intended by the L1 headers. --mikeu ^talk 19:26, 30 January 2016 (UTC)

Note: the Android Wikipedia app can be used to browse and edit wv by simply typing v: in the search box. It allows you to login and view your watchlist. In a browser you can also use the Mobile view button at the bottom of every page to test how a page looks mobile on a desktop computer. --mikeu ^talk 19:26, 30 January 2016 (UTC)

Support My own three cases were 2 "typos", and a mysterious case where the bot may have been in error. As to whether they should be changed by hand or by bot depends on how well you trust the bots, something outside my expertise. --Guy vandegrift (discuss • contribs) 19:52, 30 January 2016 (UTC)

Based on initial strong support, I've updated the bot to add the category to all content pages with Level 1 headings. I've also written a bot fix for pages that have only Level 1 headings, as these are easily converted to Level 2 headings with very low risk of error. -- Dave Braunschweig (discuss • contribs) 21:47, 30 January 2016 (UTC)

 Comment I agree with actions of inclusiveness! But, I have some questions

1. With the rapid updates in software that occur, are any screen readers actually still affected by the multiple <H1> headings per page? One reason for having multiple level 1 headers is for effect rather than viewing pleasure.
2. User mikeu above has commented on mobile readers and editors, which was also a concern of mine mentioned on Talk:Genealogy, is he indicating that mobile access is being affected by multiple level 1 headings?
3. I have checked editing on a number of pages that use Big between <> to give the effect of a section heading of the same size as a level 1 heading, would this, or perhaps something similar, be an acceptable alternative to multiple level 1 headings so that the effect can remain? --Marshallsumter (discuss • contribs) 23:17, 30 January 2016 (UTC)

I ran a test on the resource Pluto. Replacing e.g. =[[Research]]= with ==<Big>[[Research]]</Big>==. It does have the effect of making the section title the same size as a Level 1 heading! In your haste to begin bot processing you may be making many of us, at least me, have to go through and change perhaps hundreds and worse a few thousand resource headings back to the appearance of level 1. How about having the bot switch the level one heading for the Big heading just to be sure? Then you won't need to increase the number of "="s on the multiple levels. --Marshallsumter (discuss • contribs) 23:44, 30 January 2016 (UTC)

We need to be very clear that a section header is NOT a style markup like italics or bold, even though it has a style change as a side effect. These headers are "machine readable" code and are used by software for a number of purposes such as generating a table of contents. These should not be changed just because someone doesn't like the size of the font, as automated parsing of this code can be fragile. OMG, Pluto is a nightmare of mobile (un)usability. The convoluted markup breaks everything. In a mobile view there is no table of contents. The default view is that text beneath a level 2 is collapsed and you only see a list of L2 headers. Clicking on a header causes that section's text to "drop down" and expand. By placing a hyperlink in the header it is impossible to open the section and see any of the text, as touching the header "clicks" you through to the hyperlink instead. Any page that uses this scheme is completely unusable/unreadable on a mobile device. I'm seriously considering proposing that we discuss a mandatory style guide to prevent to prevent misuse of these wiki features. I have no idea what the ramifications of placing <big> inside a header are, but I strongly discourage using this scheme. We have no idea what the unintended consequences are for site usability. --mikeu ^talk 00:13, 31 January 2016 (UTC)

Thanks for checking this! There may be many resources, I do not know how many I've seen, that use <Big>Section title</Big> or the big text somewhere else that may be affecting mobile devices in some adverse way.

Also, thanks for the positive effort to address my concerns. I can now Support Dave's effort to replace level 1 headings with level 2 on those resources currently only using level 1 headings. I'll wait on the multiple level resources until we see what problems if any are encountered. And, as the creator of the Pluto resource I will be happy to remove the big notation. --Marshallsumter (discuss • contribs) 00:35, 31 January 2016 (UTC)

I agree regarding concerns on customizing headings. We need to start a list of things that don't work correctly (such as links in headings) and make corrections as time allows. -- Dave Braunschweig (discuss • contribs) 00:24, 31 January 2016 (UTC)

I did some searching on the accessibility guidelines before starting this effort. There are some changes in HTML 5 headings, but only because HTML 5 eliminates the need to use levels. It has a <H> tag without any numbers, and that tag can be used for all levels. HTML 5 then processes the levels automatically rather than specifying.

But, HTML 5 did not remove the other levels, and I can't find anything that says the accessibility guidelines have been changed for the numbered tags, which is what we have.

According to http://www.w3schools.com/tags/tag_big.asp, the <big> tag is no longer supported. We need to change these to a CSS solution instead. See Wikipedia:Template:Big for an appropriate alternative and explanation. We should import all of the sizing templates listed there, and convert any of our outdated content and templates to current standards.

An easy way to tell if it is current or outdated is that anything current should be in relative measurements. Sizes should be in percentages rather than any absolute numbers. Widths and heights should be in multiples of em sizes, or something very similar. If it has px measurements, it's outdated. If you have any questions on what's current vs. outdated, or need any assistance, let me know.

Regarding replacing the Level 1 headings with {{big}}, that addresses the appearance issue, but not the navigation issue. All of these headings are still headings, and as far as I know need to remain as headings so that users can navigate the page using the Table of Contents.

Once we figure out the standard formatting, I'd be happy to work with you on bot code you could use to increase the size of Level 2 headings on learning projects you frequent, assuming that we can find a way to do it consistently and effectively. But, please consider whether this sizing is something that you want/need to force on all users seeing those pages, or whether it is something that you want to have for yourself. You can set your own custom CSS file that would apply to all pages you view without any page editing at all. That is the preferred approach, as it allows each user to control their own view based on standard formatting.

Dave Braunschweig (discuss • contribs) 00:24, 31 January 2016 (UTC)

Mobile view of our Main Page

There is an explanation of things to avoid (and why) when using section headers at meta:Help:Section. Please tell us more about why you think you need the header text bigger. There may be some method for highlighting or otherwise enhancing the appearance, perhaps big is not the best solution. I am unclear as to what problem you are trying to solve. Also, the big tag in a section does not have the same appearance on a mobile device. It is very difficult to ensure that non-standard markup looks the same for every device that someone might use. We know that the standard use of headers works as this has been exhaustively tested by mw developers. While I can sympathize with the desire to customize the look of a lesson this is often self-defeating. (all of the text at Pluto was invisible on my phone)

In general I would avoid putting anything between the "=" headers, esp. markup, and never place anything after the closing "=" on the same line. I would even avoid non-standard characters in section titles. Remember that a section is linkable using Pagename#section and any character in a section title will get converted to an URL, for example "?" is replaced by "?"

Recently I've been browsing pages on mobile to test usability. The list of problems is long. Take a look at this screenshot of the entire Main Page. There is almost nothing left of the pretty boxes that show up on a desktop. This is clearly not useful to mobile visitors, who may make up nearly 1/2 of our audience. --mikeu ^talk 01:39, 31 January 2016 (UTC)

How do our portals look on a mobile phone?

I've run into the variations between urls and section titles before but the improvements in the url software usually handles these. The mobile phones are another matter entirely. There popularity may have one of two effects: Force wikis like ours to change our coding (best handled by mw) or force the software changes within mobile phones to better accommodate main frame nuances. --Marshallsumter (discuss • contribs) 02:11, 31 January 2016 (UTC)

See https://en.m.wikiversity.org/w/index.php?title=Portal:Agriculture&mobileaction=toggle_view_mobile for an example of how the new portal design looks on mobile. Shrink the borders of your browser to see how it looks on different screen sizes. Use the Mobile link at the bottom of any page to see how that page looks on mobile. -- Dave Braunschweig (discuss • contribs) 02:17, 31 January 2016 (UTC)

This portal is great! Awesome! May they all be this good. I'm happy to have contributed my small bit by creating the agriculture lecture resource. --Marshallsumter (discuss • contribs) 02:14, 1 February 2016 (UTC)

The old portal design is badly broken. Dave's new design looks and works well. See Colloquium for discussion on mobile portals. --mikeu ^talk 02:37, 31 January 2016 (UTC)

---

Level 1 headings have now been cleaned up. Most were changed to level 2 headings, with other headings on the page cascaded appropriately. Some Level 1 headings were changed to just being a larger font if they didn't appear to add navigational value to the page. A few were removed if they were at the top of the page and matched the page title. If anyone finds pages that were updated incorrectly, let me know and I'll check into it. -- Dave Braunschweig (discuss • contribs) 03:07, 13 February 2016 (UTC)

Formatted Headings

I don't know if anyone will need these, but for reference based on current Mediawiki CSS, the heading fonts can be emulated using the code embedded here:

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Or:

{{font|font=Georgia;|size=1.8em|Heading 1}}
{{font|font=Georgia;|size=1.5em|Heading 2}}
{{big|'''Heading 3'''}}
'''Heading 4'''
'''Heading 5'''
'''Heading 6'''

Note that the Georgia font may not exist on all platforms.

Dave Braunschweig (discuss • contribs) 03:56, 31 January 2016 (UTC)

The approaches above would generate text that looks like a heading, but doesn't support navigation. To resolve this, templates that support navigation and formatting have been created. They generate valid HTML and work as navigation placeholders, but do not include Edit links. Use is not recommended, but would be the best alternative for styling headings. See:

• {{H1}}
• {{H2}}
• {{H3}}
• {{H4}}
• {{H5}}
• {{H6}}

Dave Braunschweig (discuss • contribs) 14:48, 31 January 2016 (UTC)

update

I just blew away a large section of text that gave some very bad advice about custom formatting pages. I've been "guilty" of this myself as I have placed links in headers in the Colloquium. This style guide needs to be re-written to take into account best practices for usability and adopted as an official policy. --mikeu ^talk 07:48, 31 January 2016 (UTC)

Links in Headings

Links should be avoided in top-level (Level 2) headings. The links disrupt mobile navigation. Links appear to be okay in Level 3 and higher headings, as those headings are not used for collapsed display. -- Dave Braunschweig (discuss • contribs) 18:23, 31 January 2016 (UTC)

I was just about to add a note explaining that.... How does markup affect <Hn> headers? Are there any other ramifications to having links or wiki syntax in a Level 3 header? I'm thinking of the Candidates for Custodianship page which has "Mu301 (talk • email • contribs • stats • logs • global account)" section titles and similar. I'm thinking of posting a note to meta asking that mass message delivery not include links in headers for notes posted to our colloquium. I'm a bit surprised that this hasn't been discussed there before. --mikeu ^talk 19:35, 1 February 2016 (UTC)

I don't think markup is the issue, just links. And the reason it is an issue is because Mediawiki uses the headings to collapse content on mobile, and clicking on the link to expand instead navigates to that link. As tested, it wasn't an issue for Level 3 and higher, as long as there is a Level 2 there first. But, yes, definitely this should be brought up at meta.

Separate from the technical issue, I'm personally not a fan of links in headings. It is often done internally (RfD, Custodianship, etc.), but perhaps this is just a cultural (past practice) approach and there's a better way.

Dave Braunschweig (discuss • contribs) 21:52, 1 February 2016 (UTC)

I posted a request to [MassMessage at meta explaining the problem and asking them to not put links in headers of edits here. I think our style guide should "prohibit" links in L2 headers (with scheduled cleanup by bot if needed.) I would support "discouraging" links or other wiki markup in all section titles. I really can't see a compelling need for putting content like that in a header. --mikeu ^talk 23:07, 1 February 2016 (UTC)