KDE Developer portal

[Carl Schwan]

Le dimanche, juillet 12, 2020 8:01 PM, Ivana Isadora Devcic <skadinna at gmail.com> a écrit :

> Hi Carl,

Hi Ivana,

Thanks for proposing your help. I gave you access to the repository and started creating tasks so that others can pick up some of them. Like you said the most important for now is to write down how to create an article, preview it locally, and publish it. I just wrote a small introduction about it in the project's README.md but it will require a bit more work to make it easy to contribute.

Cheers,
Carl

>
> I'm really happy that you've decided to work on this, knowing how busy you are with all the other website and promo-related tasks. You probably already know that I think this effort is absolutely worth it. :)
>
> Although I was too tied up with my day job stuff and unable to lead this as a community goal, I want to help and work on this with you. I can port articles to the new format, create promotional content, and edit articles written by others.
>
> As for the platform/tooling choice...my experience with Hugo is somewhat limited, so I can't really judge. I've used Sphinx a lot, but I'm aware of its disadvantages. I know how to make a custom theme, but extending the functionality of Sphinx would be challenging. Honestly, if you find Hugo more comfortable to maintain and upgrade, I'm all for it - I can learn how to work with it. The "old" wiki is a bit clunky, and the user experience of creating and updating content there was never really pleasant for me, so I would be in favor of replacing it. But I understand some people might oppose moving away from it.
>
> From my perspective, it's more important to prepare instructions on HOW to maintain this portal, how to add new things, how to resolve potential issues... Regardless of the tool, we should make sure the process is transparent so that anyone can pick up and help, instead of having to rely on one or two people to always do everything.
>
> Either way, whichever solution we choose, you can count on me to help with the content. And again, thank you so much for working on this!
>
> Cheers,
> Ivana Isadora
>
> Den sön 12 juli 2020 kl 00:29 skrev Carl Schwan <carl at carlschwan.eu>:
>
> > Hello everyone,
> >
> > Some of you probably saw the "First-class user & developer documentation centralized on a portal" goal proposal by Isadora one year ago (https://phabricator.kde.org/T11096). I shared Isadora's opinion, of having a good developer portal with all the information on how to use the KDE Frameworks, could help with third-parties' use of them, and also help with the onboarding of new developers.
> >
> > Sadly it wasn't voted but in the same direction, I experiment with creating such a developer portal for KDE using the static site generator Hugo and the docsy theme. The result with a few converted articles can be seen here: http://kde.carlschwan.eu/docs/.
> >
> > Current advantages of docsy and Hugo over the current Mediawiki install at techbase.kde.org are:
> >
> > * It is possible to have code examples that can be compiled and shared as tars. This make it easier to have an automatic test ensuring that the code in the examples works.
> > * The content gets automatically organized in section and with easy navigation between the sections.
> > * It is also possible to create promotional content of our developer libraries and tools as can be seen here http://kde.carlschwan.eu (I need to put more work on it), news pages, and other types of pages.
> > * It is possible to host multiple separate documentation on the same instance so that it could be possible in the future to move stuff like docs.plasma-mobile.org and hig.kde.org to the same instance so that search would work across the projects.
> > * One less wiki instance to maintain (there are pains to maintain and update).
> >
> > Moving from a Wiki also has some disadvantages, first, we need to port all the content but it would be a good occasion to update them to Qt5 and KF5. This will be a lot of work so help will be needed. And it will make it slightly more difficult to contribute since unlike a wiki it uses git, but in the sidebar, a link is included and directly open the GitLab web editor for the open webpage.
> >
> > There is also the possibility to move to Sphinx, as some other KDE projects did, and I have a small demo here: https://invent.kde.org/carlschwan/techbase-kde-org. Problems with sphinx are that the theming isn't easy and it is a lot more difficult to create great promotional content with it. It also has a small advantage that a Doxygen integration already exists, so it easy to link to api.kde.org classes and methods but I have an idea of how to create a similar integration in Hugo.
> >
> > So my question now to the community is the effort worth it? and who would like to work on it with me? ;) It doesn't necessarily need technical knowledge, but we need to work on the promotional content, porting the old articles to a similar but different format, updating them to Qt5 and KF5 (and maybe also writing new articles about Kirigami/Android/... for examples).
> >
> > Cheers,
> > Carl
> >
> > PS: The dark theme is broken, I know already :(