Talk:Documentation

Documents

Is there any pdf for online documentation ? — Preceding unsigned comment added by 193.255.177.29 (talk • contribs) 14:50, 22 May 2015

Revisions to this and related pages

Just an FYI, I am working on revising this Documentation landing page and its subpages to better cover the typical questions people have about tech docs and to surface the various templates, checklists, and other resources tech writers have been working on in the past years. Tracking bug is https://phabricator.wikimedia.org/T277128 TBurmeister (WMF) (talk) 16:34, 21 October 2022 (UTC)

Would documentation office hours be useful to you?

Tech writers on the Developer Advocacy team are interested in providing a recurring time for anyone to come ask questions about Wikimedia technical documentation and get help with writing and/or improving docs.

1) Would this be something you would find useful? If so, how might it be useful to you? 2) Which platform(s) would you like to see it on? 3) What format(s) would you like -- a synchronous chat without video? a video meeting? other ideas?

We're looking for any and all feedback, as this is just in the idea stage for now. Please reply to this post and let us know your thoughts. Thanks! TBurmeister (WMF) (talk) 15:52, 16 November 2022 (UTC)

Setting up auto-archiving for this page

Hello, I would like to start using Template:Auto archiving to auto-archive comments older than 2 years on this Talk page. Please comment here if you have any objections or feedback on that. If I hear no objections, I will proceed to implement auto-archiving at the end of this month (June 2025). Thanks! TBurmeister (WMF) (talk) 16:15, 9 June 2025 (UTC)

Hi, Tricia! Given the very low frequency of messages in this talk page, I would suggest using a longer period before archiving the threads. For example, even with a generous period of 10 years, only 3 messages would remain in this talk page, which seems quite manageable to me. — Waldyrious (talk) 21:42, 9 June 2025 (UTC)

That makes sense! I agree a longer time frame would make sense. Part of the reason I was asking about this now is because we have some upcoming announcements that may generate more comments on this page. So I was proactively trying to make the page a bit shorter in case it starts getting a bit more traffic. TBurmeister (WMF) (talk) 14:53, 10 June 2025 (UTC)

I see! Looking forward to those :) I'd say we could start with a low archival frequency, and bump it up in case the page starts getting unwieldy. WDYT? Waldyrious (talk) 14:53, 13 June 2025 (UTC)

SGTM; thanks for sharing your thoughts, it's nice to get input and exchange ideas! TBurmeister (WMF) (talk) 18:26, 13 June 2025 (UTC)

Posts older than 10 years are now at Talk:Documentation/Archives. TBurmeister (WMF) (talk) 14:55, 26 June 2025 (UTC)

UI feature request and suggestions for Documentation Linter

I was checking out the Documentation Linter at https://techdoc-linter.toolforge.org/, running it on some technical reports of mine, and one suggestion I have is to do some sort of highlighting in the snippets to make it easier to find the text being discussed. It may be less necessary for long sentences (though It told me one sentence was too long but the snippet had two sentences) or for end punctuation in headings, but for things like passive voice, Latin abbreviations, or potentially frustrating words, a highlight of the exact phrase would make it easier to find in the snippet.

Related to end punctuation, should question marks be excluded from the list of unacceptable end punctuation? Is it worth trying to get a list of words that always have periods in them (like etc.) that should be ignored? Is it worth identifying acronyms? (I haven't found any live examples to test, but F.A.Q. or T.B.D. or similar could occur.)

I also noticed that the linter seems to at least sometimes be working on the wikitext, rather than the surface text. "> 2%" was tagged for using an ampersand because ">" is underlyingly ">".

TJones (WMF) (talk) 20:43, 23 June 2025 (UTC)

• +1 to adding highlights (if feasible).
• For end-punctuation, I would guess this is (also?) trying to help us avoid the problem of T50940 ("Punctuation like ".", "?" and "!" at the end of page title in links not interpreted as part of the URL by various applications"), and question marks are the most frequent source of these errors, so I hope we can keep/include those in the lint-rule. I.e. I've memorized %3F and check URLs for "?" before I post them anywhere, because this bug bites me weekly. (See also: w:User:Quiddity/Problems with punctuation in links for more examples and related-links)
  • If true, (or a happy accident / additional bonus reason to remove end punctuation in headings!) I'd suggest documenting that aspect at Documentation/Tools/Linting/Linter rule reference#Wikimedia.HeadingPunctuation

HTH, and thanks again for this tool. Quiddity (WMF) (talk) 21:47, 23 June 2025 (UTC)

Regarding end punctuation in headings, I'd also point to markdownlint's rule for this, which defaults to forbid .,;:! and their fullwidth equivalents, as an additional data point to consider. ? Is explicitly mentioned in the rule's documentation as allowed by default due to its prevalence. Waldyrious (talk) 08:59, 24 June 2025 (UTC)

Perhaps it would be feasible to split our rule into 2, with 1 strongly discouraging the majority of punctuation, and one weakly discouraging the use of "?" (especially in page-titles, and perhaps in main headings). Quiddity (WMF) (talk) 17:56, 24 June 2025 (UTC)

These are excellent points, thank you for your feedback!

1. Highlights - we actually had a prototype that did this, but the code behind it was a bit untidy and would have been difficult to maintain, so we decided to skip it for now. We will revisit this and look for ways to implement highlights in the future.

2. End punctuation in headings - everyone's comments about this are very interesting. I'll bring this up for discussion with the team. The rule is deliberately quite general. We thought that codifying specific exceptions would make it confusing, less helpful, and prone to false positives. We'll look at this again.

3. False positives: Sentence length warning for a snippet with two sentences; Ampersand suggestion - these happened sometimes in our testing. If you could share the titles of pages with these issues, I'd investigate this further. KBach-WMF (talk) 09:40, 25 June 2025 (UTC)

I can't find the ampersand example anymore, but I've copied a bit of text that causes a two-sentence snippet to User:TJones_(WMF)/Notes/Sandbox here on Mediawiki.org. TJones (WMF) (talk) 20:44, 25 June 2025 (UTC)

Perfect, thank you! Looks like the warning applies to the second sentence in that snippet. I'll see if I can find a way to make it clear in the UI. KBach-WMF (talk) 06:33, 26 June 2025 (UTC)

I have now deployed a version of the linter web app that includes highlights. Please let me know if it works as expected. KBach-WMF (talk) 07:36, 30 June 2025 (UTC)

Nice! One small issue I see is that the "punctuation in headings" suggestion highlights the punctuation, and the letter before it. So "Heading?" gets highlighted as "Heading?" I've updated User:TJones_(WMF)/Notes/Sandbox here on Mediawiki.org to include two examples with punctuation. TJones (WMF) (talk) 16:56, 30 June 2025 (UTC)

Thanks! I'll see if I can change that behavior. KBach-WMF (talk) 10:29, 2 July 2025 (UTC)

This is now fixed! KBach-WMF (talk) 06:24, 4 August 2025 (UTC)

We've decided to keep the end punctuation rules as they are for now. We realize the current configuration isn't perfect, but we think it's a reasonable compromise between usefulness and maintainability. That said, we intend to keep this feedback in mind as we make further improvements to the rules. KBach-WMF (talk) 07:49, 4 August 2025 (UTC)

"More..." Rule in Linter

Hello, I was checking out the linter and noticed that "more..." was flagged, with the rule being cited "Avoid '...' outside code samples." However, this is a very common button/link text on websites and apps to cut longer text off and probably needs to be removed from the linter if enclosed within an anchor/button tag (or maybe something could be added stating it is acceptable if enclosed within an anchor/button tag).

Thank you! ~2025-24927-8 (talk) 22:06, 22 July 2025 (UTC)

Sorry for the late reply - I've missed this comment somehow. Can you share an example? I'll bring this up for discussion with the team. KBach-WMF (talk) 06:46, 4 August 2025 (UTC)

After consulting with the team, I've added a clarification for the situation I think you're describing to the reference: Wikimedia.Ellipses Explanation. Hope this helps! KBach-WMF (talk) 08:27, 9 October 2025 (UTC)