Qt Contributors Summit 2019 Program/Qt for Python Documentation: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(Notes for Py Docs)
 
Line 1: Line 1:
== Ideas to improve the docs ==
== Ideas to improve the docs ==


* flutter.dev is a good example of documentation
* [https://flutter.dev/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 to beginners;
** Add a Widgets catalog might be useful for beginners;
# The distribution makes sense, add a first steps link, a link for the widgets, to the API docs, a couple of tutorials;
** 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 view 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;
* A simplified overview of the general documentation is missing;
* Adding an image explaining what is which widget in ta simple interface might be simple;
* 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;
* WebAssembly might help, you can create an interactive widget that will show you what are the widgets in the layout;
* 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
* We can remove the deprecated stuff from the wiki;
** WebAssembly might help, you can create an interactive widget that will show you what are the widgets in the layout;
* Sometimes documentation isn't in the snippet files;
* 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;
* Adding tabs on the docs to quickly switch from Qt to Qt for Python is a dream;
* Go through everything is a big work for human inputs, machines can't do much here
* 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;
** Maybe we can bribe them with chocolates;
* We should add images to the docs to the tutorials and pictures to the widget gallery, people like it and it's more easy to understand what's happening
** Create a get together day internally so employees can contribute to this;
# Maybe we should have a separate repo for images because it'd get too heavy;
** 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;
# Make the docs more interactive and give the opportunity to run code in a webpage and generate a screenshot from this code;
 
* QtNotebooks: for the tutorials. Creating something like this might help the beginners to get involved;
* 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
* We should transfer everything from the wiki to the docs;
** 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 [https://rasa.com/docs/rasa/user-guide/rasa-tutorial/ 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
* 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;
** 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";
** 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;
 
* Having .svg animations to show how to start to stuff, how to build Qt for Python, for example;


== Currently what we have ==
== Currently what we have ==


=== Good things ===
=== Good things ===
* The name Qt For Python is a good thing because you don't get in touch with old stuff;
* The name Qt For Python is a good thing because you don't get with the old PySide stuff;


=== Bad things ===
=== Bad things ===
* Too confusing;
* Too confusing;
* The .rst format is a paing and we'd like to change it to .md;
* The .rst format is a pain and we'd like to change it to .md;

Revision as of 12:23, 21 November 2019

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;