Create Task
Maniphest T5439

Discuss todo/release/review process for HIG
Closed, ResolvedPublic
Actions

Description

If possible just like the rest of KDE / Plasma based on phabricator and git.

So far we discussed drafted guidelines on the special mailing list kde-guidelines@kde.org; if we move to phabricator or any other tool this ml could be removed

Most likely this means switching to something different, then the wiki.

I would suggest either something based on markup (because wiki pages are in markup?) eg http://www.sphinx-doc.org/en/stable/markup/, or if KDE / Plasma uses already something else in several similar projects use this.

Some more pros for switching from wiki:

  • Could also be done in git
  • most new images are generated from qml files, but the wiki offers no way to batch upload all of them, e.g. after the release of a new plasma version
  • much better version control. eg at the moment it's next to impossible to create and discuss a draft
  • easier inclusion of autogenerated content, eg color schemes directly from the color scheme sources
  • probably better control over the layout and more consistency in the pages

Con:

  • needs extra software to build
  • probably harder to contribute for someone new
  • findability, searchability

Related Objects

fabianr created this task.Feb 21 2017, 1:23 PM
romangg added a subscriber: romangg.Feb 21 2017, 7:46 PM

Phabricator has a wiki with the general good looks and editing functionality of Phabricator: https://phabricator.kde.org/w/
Could this be suitable? In the end the guidelines need to land in the officital wiki though aswell.

fabianr added a comment.Aug 30 2017, 7:57 AM

Other tool that could be used :

alex-l added a subscriber: alex-l.Sep 11 2017, 10:31 AM

+1, in particular for Grav

alex-l added a comment.Sep 11 2017, 10:35 AM

Pelican seems very good too

argonel added a subscriber: argonel.Sep 14 2017, 12:23 AM

The cons of moving away from mediawiki for the HIG are:

  • requirement of another set of systems for sysadmin to support - webserver, CMS, other integration tools, DNS, bug reports, other things I don't know off the top of my head because I'm not a sysadmin
  • some docs then exist in a different place, with a different nav structure and appearance -> fragmentation
  • the bus factor of those that asked for the "new hotness" in CMS (a term which i use loosely) find other projects that take them away from KDE, leaving sysadmin to try and maintain aging infrastructure and devs trying to make do with a foreign system
  • the learning curve for the new people that come along, with or without support from the current team, trying to adapt themselves to the setup, instead of being able to get right to work in mediawiki

I don't understand "easier inclusion of autogenerated content, eg color schemes directly from the color scheme sources"

colomar added a subscriber: colomar.Nov 6 2017, 1:11 PM

much better version control. eg at the moment it's next to impossible to create and discuss a draft

I don't get that point. Version control is one of the key features of a wiki. Some Wikipedia articles have up to thousands or tens of thousands of edits with hot debate around them, so if it works for them, why doesn't it work for us?

fabianr added a comment.Feb 2 2018, 11:16 AM

My main problem with the version control is, that you can't have a "draft".
I can not work on a page in a branch, discuss it with VDG, improve it, change it, repeat the process and only when I think it is done commit it.

You always work with on the live master version.

fabianr closed this task as Resolved.Jul 24 2018, 7:10 AM
fabianr claimed this task.

So far using git, phabricator and sphinx works really well.

There is an actual review process now for the HIG pages, one can discuss drafts on different branches and the HIG pages work ok on mobile