Technical Document Re-working Group/Meetings/2018-03-16
Jump to navigation Jump to search
Date -- March 16, 2018
- 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
- 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."