[Matplotlib-devel] Documentation Summit

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view

[Matplotlib-devel] Documentation Summit

The Matplotlib development team is planning a 2 day documentation sprint / summit in Denver for late summer 2019 and have some travel funds. If you are interested in attending (either in person or calling in) please fill out http://bit.ly/docsum19

The purpose of this summit is to:
  • write a work-plan for 9-12 months of work for a technical writer
    • including rough outlines, deliverable, and milestones
  • write a budget (technical writer + core dev time to manage / review)
  • write short grant to submit to foundations (4-6 pages, ~100k)
To achieve these goals, the summit participants will identify problems with the Matplotlib documentation, including:
  • it is too big to effectively use (over 3k pages of content)
  • it is incomplete (many methods lack sufficient API documentation and examples)
  • there is no consistent voice through out the documentation
  • there is no clear path through the docs
  • the same content is serving many different audiences
    • existing users looking for API docs
    • new-to-python users looking for a "quick start"
    • new-to-programming/viz, but domain experts
    • new-to-visualization users starting from scratch
  • two main audiences:
    • scientists/user
      • trying to solve a specific problem as quickly as possible
    • developer writing visualization apps/ software¬†
      • looking for detailed API docs and internal logic
The participants will then develop a work plan for addressing these issues by hiring a technical writer with a mandate to:
  • audit and sort the existing documentation
    • potentially into tutorial, reference, topic and¬† how-to guides
  • ensure complete coverage of API docs
  • de-duplicate the examples and tutorials
    • sort out what the per-requisites are and link appropriately
    • develop curated "paths" through examples / API doc
  • develop "quick reference" sheets
  • develop a template for domain specific intro material
    • implement several of these?
  • develop coding and documentation style guides
  • identify missing tutorials
  • scrape stackoverflow and otherwise engage with the community to determine what is missing
and other such tasks. The technical writer will be expected to work with the developers to cover knowledge gaps.

Please reply to this email with questions, comments, complaints, and suggestion and please fill out http://bit.ly/docsum19 if you are interested in attending remotely or in person.


Matplotlib-devel mailing list
[hidden email]