Talk:Documentation/Contribute
Add topicLatest comment: 1 year ago by TBurmeister (WMF) in topic Idea to restructure page content
Idea to restructure page content
[edit]With the goal of trying to make it simpler for people to get started contributing to tech docs, I'm wondering if we could adjust the content and structure of the "How to contribute to Wikimedia tech docs" section, to separate the content by code-based vs. wiki-based doc contributions. This would make it easier to focus on reading only the information / links relevant to the type of doc contribution you want to make, and it would help us cover code-related topics more thoroughly (see "proposed additions" below for what I think is missing).
The following is an attempt to redistribute, for each page section (in bold), the current information on the page into sections for on-wiki workflows vs. docs-with-code workflows:
These intital pieces of info are relevant to both on-wiki or in-code docs:
- Before you start:
- "Read and follow the Communication tips and Wikimedia's Code of conduct." (Communication tips is very developer-focused, but I wasn't able to find any similar resource that contains this useful behavioral guidance, so I think this must stay for both types of doc work. The code-based workflow includes another link to a different part of the New_Developers page with other steps that on-wiki contributors needn't worry about).
- Find doc tasks:
- (This whole section is relevant for both types of docs)
- Proposed addition of new section: Choose doc format and location:
- (This is the point where workflows branch off. After this, there is some duplicate content but not much.)
- (Could link to Documentation/Find_docs. In this step, contributors should identify where existing docs are and emulate that in their contribution, or they should use info in the previous sections to ask for guidance about where and in what format to publish.)
The following are only relevant for on-wiki docs (listing by section):
- Before editing a wiki page:
- "For documentation on wikis, collaborators interact on the Talk pages, but may also use Phabricator tasks, mailing lists and additional group chats like IRC." (proposed addition: link to Communication)
- Learn the basics of wiki editing.
- While working with on-wiki docs:
- (Duplicate info): Follow the technical documentation style guide.
- (Duplicate info): If you're starting a new doc, use a template(Update link) to help you create and structure your content.
- Working with translated content: I propose we remove this section, and replace it with a link to an appropriate page that captures these key points, but also includes the additional info people need to know when working with translated pages. Maybe one of the resources listed at Documentation/Technical_style_guides_and_templates#Translation, or whatever is best candidate based on phab:T391616.
- Before you publish a wiki page:
- (Remove:"Review what you wrote to make sure you use inclusive language." This is covered in the review checklists mentioned in the next bullet point)
- Use a checklist to review your doc for common issues and key quality criteria. (change: link to specific checklist)
- Remove any templates you may have added while editing, like {{DoNotTranslate}}, {{Draft}} or {{Work in progress]}.
The following are only relevant for docs stored with or in code (listing by section):
- Before editing documentation stored with code:
- Read and follow the steps for How to start contributing.
- (Proposed addition): Verify the project you want to contribute to is accepting contributions. Look for a CONTRIBUTING.md file or section in the project's README.
- "For documentation stored with (or within) code, collaborators interact using standard code review procedures on Gerrit, GitHub, or GitLab(proposed additions:GitHub and GitLab), but may also use Phabricator tasks, mailing lists and additional group chats like IRC." (proposed addition: link to Communication)
- (Proposed addition) For documentation files stored with code: be familiar with the basics of markdown editing. (Add link to a resource)
- While working on docs stored with code:
- (Duplicate info): Follow the technical documentation style guide.
- (Duplicate info): If you're starting a new doc, use a template(Update link) to help you create and structure your content.
- (Proposed addition) For documentation strings stored in code: follow Coding conventions for that programming language.(Add link)
- Before you send a patch for review:
- (Proposed addition) Review the code review process for the project, including commit message guidelines.
- (Remove:"Review what you wrote to make sure you use inclusive language." This is covered in the review checklists mentioned in the next bullet point)
- Use a checklist to review your doc for common issues and key quality criteria. (change: link to specific checklist).
- (FUTURE AWESOME OPTION / addition): Run a doc linting tool on your file to identify common issues.
(This section is mostly the same for both workflows, so it could be shared like it is now)
- After you publish
- Verify that your changes follow accessibility guidelines. Use the WAVE tool to check for major issues.
- View your content on a mobile device and check that it renders correctly and that all information is visible.
- Monitor the relevant Talk page, Phabricator task, or other communication forums. Reply to comments or feedback on your changes.
Visual diagram of the proposed page structure for this section:
How to contribute to tech docs
│
▼
Before you start
│
▼
Find doc tasks
│
▼
Choose doc format and location
Before editing wiki page ◄──────────────┘ └──────────────────► Before editing docs in code
│ │
▼ ▼
While working on-wiki While working in code
│ │
▼ ▼
Before you publish Before you send a patch
│ │
│ │
└─────────────────────────► After publishing◄──────────────────────┘
TBurmeister (WMF) (talk) 19:11, 2 June 2025 (UTC)
- Re "starting a new doc": May also want to cover the URI path. I see a lot of good-faith docs by community newcomers (e.g. Hackathons) created as a top-level page on a wiki, with no links in the page content. While they likely should be a subpage of some existing page ("search first what's already there!") or at least provide some basic context. Bonus points for somehow covering mediawiki.org vs meta.wikimedia.org vs wikitech.wikimedia.org (cf T324210). AKlapper (WMF) (talk) 20:32, 2 June 2025 (UTC)
- This sounds great! Thank you for writing this up. Especially +1 to deduplicating the translation content. The right page to link to is Help:Extension:Translate/Page translation administration. --APaskulin (WMF) (talk) 19:58, 3 June 2025 (UTC)
- These changes have now been implemented! Thanks for the feedback. TBurmeister (WMF) (talk) 18:10, 26 June 2025 (UTC)