Qt Contributors Summit 2019 Program/Qt for Python Documentation

From Qt Wiki
Jump to: navigation, search

Ideas to improve the docs

  • flutter.dev is a good example of documentation and we'd like to take some inspiration from them
    • Add a Widgets catalog might be useful for beginners;
    • The distribution that they're using makes sense: add a first steps link, a link for the widgets, to the API docs, a couple of tutorials;
  • A simplified overview of the general documentation is missing;
  • Looking at the Design Studio documentation there is a new kind of documentation with simple and illustrated steps to get something done, maybe we could incorporate it to our docs;
  • Adding an image of a simple example program and explain what are the widgets and other components used to create the program shown in the image might be a good reference for beginners
    • WebAssembly might help, you can create an interactive widget that will show you what are the widgets in the layout;
  • We can and should remove the deprecated stuff from the wiki;
  • Adding tabs on the docs to quickly switch from Qt to Qt for Python is a dream;
  • Go through everything changing the text on the docs to conform with Python standards instead of cpp ones and translating the code in the docs is a mostly a work for humans, machines can't do much here
    • Maybe we can bribe them with chocolates;
    • Create a get together day internally so employees can contribute to this;
    • Not a great issue to offer to beginners because it's not interesting, but it might be okay to offer they this translation job once;
  • We should add images to the docs specially to the tutorials and pictures to the widget gallery. People like it and it's more easy to understand what's happening
    • Maybe we should have a separate repo. for images because it'd get too big;
    • Make the docs interactive: give them the opportunity to run code in the webpage and generate a screenshot from this code;
    • Also check this cool docs where you can actually run stuff;
  • QtNotebooks: for the tutorials. Creating something like this might help the beginners to get involved and experiment ;
  • We should transfer everything useful from the wiki to the docs;
  • Displaying PySide examples inside the QtCreator
    • If you have a second tab to show PySide examples and the person doesn't have PySide installed you can have something inviting people to download PySide2;
    • You can also add it to the templates. Something along the lines "Click here to download PySide2";
  • Having .svg animations to show how to start to stuff, how to build Qt for Python, for example;

Currently what we have

Good things

  • The name Qt For Python is a good thing because you don't get with the old PySide stuff;

Bad things

  • Too confusing;
  • The .rst format is a pain and we'd like to change it to .md;