Page MenuHomePhabricator

GSoD 2020: Week 3
Closed, ResolvedPublic


This task is a break-down of the third 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
    • Libraries
  • 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.

This week, I picked up from where I stopped last week and continued working on the templates. Particularly, I drafted a structure for QSGs and created a template using that structure.

Quick Start Guide

The QSG genre can be found here

  • Title - The title of the documentation.
  • Introduction - What is the documentation about?
  • Prerequisite - What do I need to know before reading this?
  • How to do A - An aspect of the documentation itself.
  • How to do B - Anther aspect of the documentation.
  • Onboarding tasks - Let people explore more about a particular software by working on tasks
  • More detailed resources - Where do I learn more about the
  • Stewardship - Where is the discussion page for this documentation? How can I reach out to the mentor

SDK and APIs

After a bit more research, I figured out that SDKs and APIs are a bit broader than I initially thought, most especially SDKs and it becomes difficult to create a single genre for both due to their nature.

An SDK is a suite of tools and includes a range of other things like libraries, code samples, documentation, and even APIs! So in context, creating a template for an SDK isn't quite ideal, in fact, documentations are a big part of an SDK toolbox!
Considering the above, I feel it would be more Ideal to create a genre for the usage of libraries rather than just SDKs!.

APIs on the other hand are protocols that aid communication between components of a software, and they are of different types. It's well beyond the scope of this genre to cover all types of API there is, but specifically, almost if not all WMF APIs are REST APIs so it makes sense to focus on just that.

However, progress on both genre can be looked up here

API Structure
  • Overview
    • URL structure
      • Versioning
    • Request format
      • Request Headers
      • Authentication
    • Response format
      • Error format
        • Error codes
        • Error Attributes
      • Successful requests
        • Structure
        • Pagination
  • API endpoints

After discussing the SDK issues with the mentors, we agreed to pivot and rather create templates for libraries(which is more specific) than for SDKs. Additionally, the SDK genre was removed from the list or genres and replaced with libraries instead.