Technical Document Re-working Group/Meetings/2018-03-16

From mediawiki.org

Date -- March 16, 2018[edit]

  • Would we pitch a documentation track at the Hack-a-thon?
    • A mix of creating new pages, analysing existing pages ("show us where you get stuck"), updating existing sections, creating new screenshots, bugfixing the tool that used to take multilingual screenshots, etc.  
  • Final Recommendation memo from BSU Students
  • Post-mortem / retro the design of working w/students. Discussed possible outreach to other universities. It would be great to talk about different ways we can engage them.
    • The prof mentioned the idea of us taking on a technical writing intern (grad student working on a final project), and I’d like to talk about this in our group. If it is feasible, it might help This could solve some of our resourcing requests -- and help us model scalable solutions for professional contributions to documentation projects.
    • Working on a WMCS/Wikimedia technical writing best practices and style guide
        • https://www.mediawiki.org/wiki/Documentation/Style_guide
        • https://www.mediawiki.org/wiki/Web_APIs_hub/Contributing#Writing_articles
        • Link to in-progrss style guide will be added soon.
        • Can we start bucketing the pages we've worked on, by various criteria? Target-audiences, doc-types (manual, reference pages, walkthroughs, tutorials, FAQs, Index, etc).
        • 4 (general) types of software documentation (tutorial, how-to, explanation, reference) -- https://www.divio.com/en/blog/documentation/ -- I like the distinction between tutorial (learning) and how-to (goal) there too
          • Most of what we currently have qualifies as "reference" or "how to." Our biggest gap is probably "walkthrough."
        • https://wikitech.wikimedia.org/wiki/Help:Toolforge/My_first_Flask_OAuth_tool for example is a swiss-cheese reference; it has many holes!
        • Are we making an organized cover-to-cover manual, or improving individual pages one-at-a-time. How do we make the incremental approach work for us?
          • Use the FAQ to fill in the Outline. Outline-first approach.
        • Other priority - getting better discussion amongst the people actively doing docs interventions.
  • Avoiding fragmentation of efforts -- discuss the Wikimedia Resource Center and its efforts to create a Style Guide for program coordinators with templates for specific genres. We should definitely get ahead of this and talk about how the WMCS | Technology Style Guide can be inclusive enough to guide how others are doing documentation across Tech and other Foundation projects.
  • Barcelona Hackathon Project -- what to bring? Possible work on a Scoring Platform Manual or Scoring Platform related doc. This is an ambitious project and probably a great one to work with community members on in terms of doing the bulk of the writing and coaching on format, style and voice. This might be a project to begin mentoring technical collaborators through completion. Also - would like to discuss engaging a design researcher to help do some interviews at the hackathon -- I think we may be able to have some help from Daisy Chen.
  • X year goal: have docs recommendations for "So you want to write a new Foo. We recommend creating these docs types, in this order."