Hackathon 2017 Documentation

Notes from documentation session

Current state of documentation

Sources of documentation:

• Examples
  • Generated from meta-language snippet and markdown template.
• Quick start page
  • Generated by sphinx
  • Unix specific
• Installation page
  • Outdated
  • Generated from markdown file in the source tree
• Showroom
  • Notebooks. Python only
• API
  • Doxygen generated
  • All classes
  • Subclasses referenced from base classes
• Developer wiki
  • Readmes from source tree
  • Various tips on developing

Problems

1. Things outdate quicker than we can maintain them
2. Too much redundancy

Questions

• Unifying documentation. We want less redundancy. How to define what goes where?
• How do we make sure that the documentation is maintained?
• Who is the documentation intended for?

Intended user groups

1. End user (Applied machine learner. Kaggler).

   • Documentation goal: What is the minimal number of steps to apply shogun to my problem
   • Story:
     • What is shogun? (1 sentence)
     • How do I install?
     • How do I run it?
     • How do I read a csv file?
     • How do apply the algorithm I'm interested in to my problem?
     • Understanding how the interface for my algorithm works. What can I do with it?
   • Trajectory: Go to website. Install. Copy paste example. Run it. Tweak it to fit my problem.

2. Developer of library (shogun team)

   • Why it is important: we need to attract developers to shogun and keep them interested.
   • Goal: one page for developing shogun
   • No documentation like style guidelines. Style and similar issues should be documented from existing code.
   • The documentation should describe how to run the tests rather than explaining CMake code
   • Dependencies
     • Can't document. They outdate
     • Core dependencies that we should document: SWIG version, CMake version, Python, C++11 compiler
     • Give pointers on how to figure out what to install
     • Specific interface dependencies. Keep documenting these
   • Story
     • I am a student. I want to develop
     • How do I compile?
     • I look at the dependencies and install
     • How do I run the tests?
     • I want a task at right difficulty level to start developing shogun.
       • Skim through github issues. Labelling system
     • Tests should be documentation.
   • C++ documentation should be part of developer documentation
   • What should we have:
     • 5 step compilation and run
     • Pointers to different concepts
       • SWIG pointers
       • Tests, build bot, travis, etc
       • How to figure out what the dependencies are

3. Someone wants to use the framework to implement an algorithm (scientist)

   • This is a future user group. Right now group 3 is a subset of group 2

Impact of future plans of Shogun to documentation

• Middle-layer scikit learn API.
  • This will change how we do user documentation.

Actions

1. Cleaning. Merge current documentation and clean

   • Die: Minimal shogun library use
   • Die: linalg backend
   • Die: test base parameter framework
     • Write meta-examples as documentation
     • write unit tests
   • Die: code and formatting style
   • Die: swig interfaces
     • merged into develop document
   • Installation readme
     • Only cover binary packages
     • Compiling manually -> developer readme

2. User documentation

   • One line on website: What is shogun?
   • One line on website: How do I install?
   • One line on website: How do I use shogun? (show very simple example, or link to )
   • Cookbook: Show full code listing
   • Cookbook: open example in notebook.
     • Connect meta example with cloud with different kernels
   • Methods signature. How do we do it?
     • GOAL: Bidirectional linking to interface specific API documentation
     • Links to doxygen can be taken out of meta-example comments. We can automatically generate doxygen links when people hover on a class or method.

• (maybe) Gather statistics on what documentation sources people use