[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-devel
Subject:    Re: KDE Developer portal
From:       Carl Schwan <carl () carlschwan ! eu>
Date:       2020-07-12 19:24:57
Message-ID: -kZvUaLZI-GSLFPVGYPtmrowbhwjiFMdv1mIAo040u511pQvpGjc4tAnpO0MWuL3aTZ95wHKJIyf-DgJWYkGJUpcSic-p3z2qzbA4T8PQBA= () carlschwan ! eu
[Download RAW message or body]

Le dimanche, juillet 12, 2020 8:01 PM, Ivana Isadora Devcic <skadinna@gmail=
.com> a =C3=A9crit=C2=A0:

> Hi Carl,

Hi Ivana,

Thanks for proposing your help. I gave you access to the repository and sta=
rted 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, previ=
ew it locally, and publish it. I just wrote a small introduction about it i=
n the project's README.md but it will require a bit more work to make it ea=
sy to contribute.

Cheers,
Carl

>
> I'm really happy that you've decided to work on this, knowing how busy yo=
u are with all the other website and promo-related tasks. You probably alre=
ady 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 a=
rticles to the new format, create promotional content, and edit articles wr=
itten 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 fun=
ctionality 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 wo=
rk with it. The "old" wiki is a bit clunky, and the user experience of crea=
ting and updating content there was never really pleasant for me, so I woul=
d be in favor of replacing it. But I understand some people might oppose mo=
ving away from it.
>
> From my perspective, it's more important to prepare instructions on HOW t=
o maintain this portal, how to add new things, how to resolve potential iss=
ues... Regardless of the tool, we should make sure the process is transpare=
nt 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 wit=
h the content. And again, thank you so much for working on this!
>
> Cheers,
> Ivana Isadora
>
> Den s=C3=B6n 12 juli 2020 kl 00:29 skrev Carl Schwan <carl@carlschwan.eu>=
:
>
> > Hello everyone,
> >
> > Some of you probably saw the "First-class user & developer documentatio=
n centralized on a portal" goal proposal by Isadora one year ago (https://p=
habricator.kde.org/T11096). I shared Isadora's opinion, of having a good de=
veloper portal with all the information on how to use the KDE Frameworks, c=
ould help with third-parties' use of them, and also help with the onboardin=
g of new developers.
> >
> > Sadly it wasn't voted but in the same direction, I experiment with crea=
ting such a developer portal for KDE using the static site generator Hugo a=
nd the docsy theme. The result with a few converted articles can be seen he=
re: 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 co=
de in the examples works.
> > * The content gets automatically organized in section and with easy nav=
igation between the sections.
> > * It is also possible to create promotional content of our developer li=
braries and tools as can be seen here http://kde.carlschwan.eu (I need to p=
ut more work on it), news pages, and other types of pages.
> > * It is possible to host multiple separate documentation on the same in=
stance so that it could be possible in the future to move stuff like docs.p=
lasma-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 u=
pdate).
> >
> > 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 K=
F5. 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 proj=
ects did, and I have a small demo here: https://invent.kde.org/carlschwan/t=
echbase-kde-org. Problems with sphinx are that the theming isn't easy and i=
t is a lot more difficult to create great promotional content with it. It a=
lso 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 t=
o create a similar integration in Hugo.
> >
> > So my question now to the community is the effort worth it? and who wou=
ld like to work on it with me? ;) It doesn't necessarily need technical kno=
wledge, but we need to work on the promotional content, porting the old art=
icles 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 :(
[prev in list] [next in list] [prev in thread] [next in thread]