Problems and hurdles with the replacement of HowDoI

Community
1

The current HowDoI wiki states Please do not add any new "How Do I" pages. Instead write a tutorial for the developer.gnome.org website i.

I see problems with the new site:

(1) No clear content boundaries given.

HowDoI gave a clear spectrum of what it should contain.
The new page does not. It simply says “tutorial”.

Expected Problems:
Some tutorials will be for ultimate beginners, some for advanced users. Rating and improvement of tutorials will become difficult.

Suggestion:
Create a site stating what granularity you expect the tutorials to be.

(2) Creation / Edit hurdle very high

HowDoIs were easy to create: Open non-existing site, click “create”, write your stuff; Edit on occasions.

The new page requires you to install software locally and to build your tutorial. Further, it does not give

Expected Problems:
Not many people will be eager to write a tutorial here. It’s much easier then to write it in a blog, in one’s own wiki or in some document (google docs / offline). The outcome is, that (again) tutorials and information will be spread on the internet and hard to find. This might lead to a value loss of GTK, as dev cost is going up with missing information.

Suggestion:
Make the system easier to approach. Even if the backend is what it is, build a wiki-style interface around it, which makes things easy to correct.

(3) Searchability / Viewability

Judging from the root page of the new site, tutorials apparently ought to be read and searched for on Gitlab.

Expected Problems:
The content won’t be searchable by search engines rendering them very unuseful for newcomers who don’t already know where to look for.

Suggestion:
Create usual html pages on gnome.org containing the content. And always put a link to the source inside the document, so users who want to edit can edit.

1 Like
2

In general, we’re trying to figure out the content for developer.gnome.org as we go along; the old website had a ton of old content, and people went to the wiki because of its minimal barrier of entry—at least until the wiki got locked down because of spam. Then the wiki started to bitrot as well.

The HowDoI/HowDoI wiki page says that you can follow the same recommendations for tutorials under developer.gnome.org. In general, tutorials are more free form, so there’s no real boundary; that’s also why they should be reviewed, instead of just dumped into a wiki page.

If your tutorial expects a certain level of additional knowledge, you should say so at the start.

That low barrier is deceptive, in more ways than one. On the one hand, you have to clear the hurdle of getting into the trusted editors group; on the other, you can dump random wiki pages that will never be edited ever again, and will just bitrot there forever. A fair chunk of the HowDoI documentation is out of date, and I had to fix it in order to port it on the developer.gnome.org website.

Additionally, the wiki gives off the wrong impression of authoritative content: people think it’s just random user generated content.

No, not really. All you need is a text editor to write reStructuredText. You need to install software—which is widely available on multiple platforms—only if you want to build the website. Changing the content can be done from the GitLab web UI; validation of the input is done via the CI pipeline. I could modify the CI pipeline to build the website in a separate job, and store the artefacts, so you wouldn’t even need to build things locally.

Please, don’t extrapolate from your own personal feelings/experience. Say that you don’t want to contribute, if you want to, but don’t invent random people on the Internet as a way to bolster your (hyperbolic) claims.

Plus: I’d love to get more people to blog about GTK, and write more documentation, even on their websites. The documentation on developer.gnome.org is for GNOME, though; and it should be written in a way that is authoritative and can be updated by GNOME developers and documentation writers—including people that wish to become GNOME developers and documentation writers.

If we wanted only to have user generated content, we could just take down developer.gnome.org and keep only Discourse and StackOverflow.

GitLab has nothing to do with the search; the search functionality is provided by Sphinx, and it’s client-side.

The generated pages are merely HTML, and are indexed by search engines—of course, at their own pace.

This is a feature request for the Furo theme.

1 Like
3

Thank you for the high level of detail on the background!

I think some of that content (e.g. content ranges) might be helpful on the introduction page. So long, hopefully this thread serves as information source for people with similar questions.

Somehow I can’t mark your post as Solution:
image

4

This topic was automatically closed 14 days after the last reply. New replies are no longer allowed.