Jump to content

Technical Document Re-working Group/Meetings/2018-01-12

From mediawiki.org

https://www.mediawiki.org/wiki/Technical_Document_Re-working_Group

Inaugural Meeting |Jan 12, 2017

[edit]

Members Present -- Sarah R , Nick, Bryan

  • Agenda
  • What are we doing?
    • Initial focused on Cloud Services and Scoring Platform
    • Want it to morph into a larger initiative
    • Have a list (below) of past efforts that we have to look back on
    • Things we need:
      • Style guide
      • Templates for different types of docs
      • 1 or 2 great improved examples to replicate
    • "We are on a journey, there are places we know we need to stop along the way. We don't know what order, and the don't know where we will end up."
    • We have project work that we would like to make progress on.
    • What do developers really need? What do they want? What format should that be available in?
    • Want to elevate documentation to in the community/ecosystem
    • Cleaning up documentation technical debt
    • Milestone steps for re-evaluation/sanity-check/retro.
  • Draft email for initial communication about SIG
    • We will send an initial email to the mailing lists regarding the SIG as we start to gain momentum and have information to share.
  • Roadmap
    • Where did we come from?
    • Where we are now?
      • Why are we doing this? What X (do we think) we are we solving for?
      • Immediate needs:
        • A thorough audit of our current technical documentation
        • Tech Documentation Style Guide & Templates appropriate to specific tasks
      • What don’t we know that we really should know?
        • These are areas for further discovery. They are not obstacles to beginning, rather things we can learn along the way  (ie. What do devs need from technical documentation? What do they want? How do they use it (really)? What’s outdated? What’s missing?)
      • Who are our allies? Who should we have on board?
        • Technical Collab
        • Write The Docs
      • What affects our current situation?
    • Where do we want to go?
      • Our Vision
        • With the understanding that our early vision is less practical than inspirational (and will evolve), what star are we following?
          • Elevate the importance of Technical Documentation on our projects; documentation will be estimated and prioritized like other deliverables.
          • Ensure technical documentation is consistent, comprehensive, accessible and meets the needs of our audiences (i.e. the documentation we create should be useful not just a requirement).
          • Foster and engage a community of technical writing contributors who are learning from our projects and contributing to them.
    • How do could we get there?
      • We could initially examine/work on:
        • Overall audience needs
        • ORES FAQ
        • Single Page structure
        • Writing tone
        • Writing style/markup
        • Categories (whether https://wikitech.wikimedia.org/wiki/Category:Documentation or (more realistically) a smaller sub-category within)
        • Main Portal pages (Help:Cloud_Services_Introduction and ORES)
        • Navboxes
        • ...
    • Where are we going? What do we want to accomplish? What is our goal beyond “better documentation?”
    • What are our obstacles (i.e. barriers to success) ?
    • What are our limitations? Not necessarily obstacles, but things we can’t alter?
    • What don’t we need to do? What is working now?
Retrieved from "https://www.mediawiki.org/w/index.php?title=Technical_Document_Re-working_Group/Meetings/2018-01-12&oldid=5870499"