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

Date -- February 16, 2018

edit

Members Present

  • Aaron H
  • Nick W
  • Sarah R.

Things to think about

  • In Progress
    • Working with the BSU students on an audit of just Toolforge documentation. Their questions are helping to surface some of the challenges we face, things we are doing well and gaps we should fill.
    • The audit and findings should be finished around 3/1/2018,and should provide a basis for more informed planning overall.
    • Focusing on ToolForge only (no ORES)
    • Questions for thought:
    • What do we know about users of our documentation? How do they find documentation? Why? Are they getting what they need?
      • Page-visits?
        • Piwik on wikitech?
        • Analytics/pageviews on wikitech?
      • Mapping of the pages? Can they/we do something like these?
        • c:File:Main Page Usability.png
        • c:File:Map of the English Wikipedia's help pages - small cropped.png
        • Or https://blog.wikimedia.org/2018/01/18/on-that-net-neutrality-clickstream-diagram/
          • (currently just avail for 10 wikis but maybe they can add)
      • Check IRC logs, Phab requests, mailing list for common Qs
  • Ongoing work -
    • Revising and cleaning up some frontline documentation -- Cloud Services Introduction, FAQ (propose changing name of this doc), and Getting Started Guide. (This is mostly fun work -- writing as a mode of learning and understanding, and revealing some areas to think about (style/voice/organization, etc).
    • Met with Halfak Re: ORES docs. We are discussing both an ORES Manual and an article that will help clarify what a model is good at and what it is not good at and why. In other words, we are starting to think about ways to tell stories that solidify understanding -- this will be a possible article on mediawiki or blog post or both.
      • E.g. Story about Italian “Ha” / Newcomer-anon vs. Experienced editor
      • E.g. Story about detecting hoaxes (and why ORES can’t directly detect them -- but can maybe help)
    • FAQ is sort of a proto-manual. Manual would look more like a directory and have more structure -- More structured (ex WikiSyntax). Use some <includeonly> or <onlyinclude> tags in the advanced subpages.
  • Next Steps Thoughts (not necessarily in any order)
    • Ongoing audit of Toolforge documentation
    • Create research based, guiding principles for style, voice, structure, which can be applied to existing and new docs regardless of document type or purpose. For  now, More a rubric than a strict guide? I very much like the basic writing rules for Simplified Technical English -- though it is not fully research based, these are good best practices
    • Identify document types being used across teams for specific purposes (How-Tos, Manuals, FAQs, Notebooks) -- come to an overall better understanding of what is being documented, where, and how
    • Work with design research and Nick and Bryan to think about simple layouts and visual cues that make reading technical documentation easier
    • Organization and discovery -- What is the best way to guide organization and discovery of technical documentation? How do the people who need it, get to it? How can we make that easier? Practical steps we can take right now -- standardizing categories, and naming conventions.
      • NW: I've made a demo of the dynamic <categorytree> tag at https://wikitech.wikimedia.org/w/index.php?title=User:Quiddity/Sandbox2&oldid=1782903
      • There are essentially Lists, Navboxes, and Categories. (And Wikiprojects - strict hierarchy in tree list).
        • Action: Nick will make some demos. Otherwise, we'll wait for BSU to get back to us with notes and (possibly) a suggested ontology.
    • Processes -- SOPs for team processes, including processes for making technical documentation happen.
    • Outreach to community writers (I think this will be easiest once we have some structural norms and processes in place to help guide what they are doing).
    • Open questions:
      • What documentation appears where.  What are best practices, acceptable exceptions, etc. "We like/don't like FAQs", "Manuals make sense in this circumstance", etc.

Barcelona Hackathon

  • Think about ways to bring tech writing and communication conversation here.