KDE Developer portal

[Ivana Isadora Devcic]

Hi 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 :(
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kde-community/attachments/20200712/e37ea89f/attachment.htm>