Minutes from the Kirigami Documentation Kickoff meeting

[Thomas Pfeiffer]

Date: 2019-04-12

Present: Notmart, Jucato, fabian, colomar, Carl

Goal: Better documentation for Kirigami

Current state of documentation:

- Api docs (good state but contributions still welcome)
- ExamplesWh (but no documentation of the examples)
- HIG (contains code but for the purpose of visualizing concepts, not as 
examples for real-world code)

Missing: Onboarding for new developers:
- high-level overview of Kirigami including architecture and components
- How to set up a Kirigami project (installing libraries, toolchain etc)
- How to package and deploy (installing on Android, running on Linux, 
distribution, etc)

Vision of Kirigami as a framework made specifically to implement the HIG 
is not clearly communicated yet, neither internally nor externally
- Does Kirigami support applications that are not conforming to the 
Kirigami HIG?
     - Not officially. One can create an application with Kirigami that 
violates the HIG, but requirements that go against the HIG probably 
won't be implemented
- Kirigami is not meant for Material Design applications. It supports 
its general visual style via QQC2 theme, but is not made to conform with 
its HIG

Apidocs intro page is outdated ("... at the moment targeted for mobile 
use (in the future desktop as well) ...")

What do we recommend to develop Kirigami applications with?
Options:
- Distro packages
- kdesrc-build
- neon or openSUSE argon/krypton in a VM?
- Docker image
- KDE flatpak runtime


Where would the new dev onboarding live?
- Start page without sphinx to allow for more freedom in visual design
- Sphinx website instead of wiki for the documentation
   - Navigation structure is in our hands
   - Possibility to include automatically generated screenshots and videos
   - Goal is to share generated assets between kirigami.kde.org and 
hig.kde.org
- kirigami.kde.org would be preferred URL
   - If sysadmin prefers to redirect that subdomain to kde.org/kirigami, 
that's okay for us

kirigami.kde.org page should contain
- Kirigami's vision
- high-level overview of Kirigami including architecture and components
- How to set up a Kirigami project (installing libraries, toolchain etc)
- How to package and deploy (installing on Android, running on Linux, 
distribution, etc)
- Documented code examples
- Communication channels (mailing list, Matrix and Telegram channels)
- Links to apidocs and HIG
- Examples of existing applications using Kirigami


The Kirigami docs page and KDE HIG will live in separate folders in the 
same repo
- fabian is figuring out how to do that technically

It would be great if the code examples could live in the apidocs, but 
currently that's difficult due to limitations in kapidocs / doxygen, so 
for now they'll live separately on the Kirigami website.
- Jucato wants to look into fixing kapidocs for QML in the future

We should get a mailing list for Kirigami ( kirigami at kde.org ) (done by 
notmart)

TODOs:
- Request infrastructure (fabian)
- Request subdomain (will be done when infra is ready)