Page MenuHomePhabricator

GSoD 2020: Week 2
Closed, ResolvedPublic

Description

This task is a break-down of the second week of GSoD based on the timeline T255360: GSoD 2020 Proposal: Improving Wikimedia's onboarding processes and documentation standards.

Related tasks for other weeks can be found here T262918: GSoD 2020

Week 2 - 4 (September 21 - October 9)
  • Carefully study Wikimedia's style guide.
  • Define the expectations of genre templates to be created for each genre.
    • Walkthroughs, How to's, and Tutorials
    • Quick Start Guides
    • APIs
    • SDKs
  • Create a template for a documentation genre that can help documentarians get started easily.
  • Create specific templates for each genre that conforms with the style guide.
  • Discuss methods that can help standardize these guides across all projects.

So this week, I focused on researching and understanding the requirements of the 3 genres selected last week, which would be immediately followed by starting templates drafts for each.

Basic genre structures

Templates should be properly structured, so documentations derived from them would have a consistent structure and feel. This particularly got me thinking about what the structure of each genre should look like and after some research, I came up with the following for each genre;

Walkthroughs, how to's and tutorials
  • Title - The documentations title
  • Table of contents - The documentation structure
  • Introduction/Overview - What is this documentation about?
  • Prerequisites - What do I need to know before reading this?
  • Installation Guide(If required) - Do I need to install anything? How do I do it? This could be a link to a QSG
  • How to do A / A tutorial - An aspect of documentation itself
  • How to do B / B tutorial - Another aspect of the documentation
  • Code Samples - How code examples should be structured
  • Conclusion - What was taught in this documentation and what has the reader learned?
  • Contact Info - Who maintains the project and how to contact them

NOTE: The walkthrough genre template is currently in development here

Quick Start Guide

The QSG has basically the same structure as the above but it only contains information sufficient enough to get the reader started and nothing more. The below sections would be added for QSGs.

  • Links to other detailed resources
API Documentation, SDK

API and SDK documentation can not fit into the same template because they can't be structured alike. Hence, it would seem ideal to split them into two separate genres.

APIs
SDKs
Random thoughts
  • When creating or editing Wiki's, specific templates can be imported and edited for certain use cases. Something of this sort can come in handy for genre templates.
    • Find out how imported templates are created.
    • Find out if they can be suitable for this use case.
    • Determine if it would be better to have templates as documents or as imports

This turned out to be a great idea and I'm making plans to work on it, additionally, it would help me learn some new stuff like creating templates, more about wikitext markup which is pretty cool. Seems like a new learning curve but would be worth it.

I've also decided to create the actual template wiki's first, after which I would create these template plugins. Hopefully, it fits well into my schedule and I'm able to pull it off.

Event Timeline

GSoD 2020 is complete!