The dream: a modern, usable, and centralized home for all KDE documentation.
Have you ever browsed online documentation of an app or an API, eyes wide open in amazement, and sighed, "Oh, I wish KDE docs were this beautiful!"?
Of course you have. Well, you know what they say - careful what you wish for, 'cause it just might come true! :)
Description
All things considered, KDE's documentation is not that bad. However, in many aspects it's incomplete; in others it's too confusing,
and it's almost universally agreed that it's too scattered and difficult to navigate, especially for newcomers.
Improving the documentation will not only improve the experience of using and developing our software, but also the reputation of the entire community.
Thanks to the great efforts of the Documentation team and our documentation specialist, there exists a momentum
and a strong awareness in the KDE community of the importance of documentation, and a willingness to invest in it.
It's time to capitalize on that.
Coincidentally, another thing that's taking off at the moment are developer portals. As a key element of the #DevRel movement,
or more specifically, the developer advocacy/developer experience culture, developer portals are succeeding in highlighting
the importance of good technical documentation. Although they are primarily used for API documentation, they can contain
other types of content - from tutorials and videos for using software, to FAQs and even support forums.
Developer portals are not only a springboard for people interested in contributing to a software project (or making use of it);
they are a tool for marketing, onboarding, community building, and expanding your business.
A good developer portal sends a message: this company/community cares about its software; cares about people making it better;
cares about ME by giving me all this information so neatly presented and organized.
In this goal, I propose we take the idea of a developer portal as a centralized place that offers the best possible experience to new developers,
and apply it to KDE documentation to build a documentation portal that offers the best possible experience to everyone interested in our work;
whether they just want to use KRunner more efficiently, or they want to develop a new Plasmoid.
To understand this goal, take a look at our current wikis; specifically, UserBase and TechBase. They are great! But they are visually outdated,
which can be off-putting to many potential new users and contributors. We can't do much to improve their usability, and sadly it leaves a lot to be improved...
Starting with search capabilities; interlinking and reusing content; providing interactive code samples; not to mention proper version control and history, or translation tools.
Now, take all those things that suck about the wikis (sorry, wikis! it's not your fault :( ).
The new solution - our shiny documentation portal - would improve all that, and more!
It would be a modern website with all the tools we need to maintain and distribute our knowledge about KDE software to the world.
This goal aims to carry the torch of the Streamlined onboarding goal from the previous round of community goals, helping further it
and assisting in accomplishing some key actions that are shared between both goals. It also launches on the wings of recent work
by the documentation specialist, aiming to continue the effort on a large scale.
In some aspects and in general sentiment, this goal is related to T11051. At the moment it seems that some efforts would overlap,
so we could consider merging or absorbing parts of that goal.
What it will take
Choosing the tools for building and/or hosting the portal
At the very least, the solution needs to accommodate single-sourcing/content reuse, integration with Git(lab?), as well as
any current documentation practices that we may wish to preserve.
For example, we may decide that we're completely happy with how user guides are currently created and maintained,
so the new solution would only be the final hosting destination where the guides would be uploaded in their current form.
Choosing the output formats
Obviously, we want to deliver the portal as a website, but we should also decide if, for example, any individual page of the documentation
should be downloadable as a PDF, or if code samples should be interactive.
Setting up the new system
We'll have to invest resources and collaborate closely with the KDE Sysadmin team to make sure everything is connected properly.
We also have to decide what the contribution process should look like: how to get access, how to suggest changes, and how to actually make them.
Reorganizing the existing information architecture
Consolidating existing content
Identifying content gaps and assigning priority to those issues
Transferring existing content to the new solution - and making it better in the process :)
Creating new content
All these actions can rely and build upon past and current efforts to analyze and improve KDE documentation.
There's a lot of useful feedback floating around, and plenty of lessons learned that can help us move forward faster and more efficiently.
Collaboration between Onboarding and Documentation teams
Close contact with KDE developers in two roles: as the target audience and as SMEs (Subject Matter Experts)
Help from the KDE Promo team, who can scout online communities to collect documentation feedback, complaints,
and requests from different types of users and developers
How we know we succeeded
- Public praise and recognition; fewer complaints about "docs that suck". KDE Promo can help with getting this data -
we can measure the predicted increase in positive reactions and experience over time.
- (Optionally) Analytics, if employed on the portal, can give us a deeper insight into how our documentation is accessed,
searched, and used. Implementing direct feedback options into the portal can help us collect impressions and understand
what people expect from the portal.
- More contributors, integrations and partners. High-quality documentation accessible in one place can open up more opportunities
for collaboration with other FOSS communities, as well as businesses and various institutions, because it helps people
who are not from our community understand our software and learn how to do things with it quickly.
- Increased Time To Value/Time To Task Completion. Note that we should conduct user research first on the current documentation resources.
We'd have to gather some baseline data that we can compare against the new solution.
What are the risks
As with most documentation-related projects, the main risk here would be content rot; in other words, the risk of content
on the portal getting outdated because contributors are not able or not interested in maintaining it regularly.
To mitigate this, we need to make sure the process of maintaining and updating the portal is well-documented to begin with,
and that it's not too complex or intimidating to new contributors.
Relevant links
- Our current resources; basically, what we're working with here. These will be our starting point; we will have to identify issues
and come up with the best solution that solves them to the benefit of all community members.
https://api.kde.org/
https://docs.kde.org/
https://techbase.kde.org/Welcome_to_KDE_TechBase
- These resources can provide a general, basic understanding of what a developer portal is
and how it relates to the concept of developer experience:
https://pronovix.com/blog/developer-portals-when-docs-become-dx
https://pronovix.com/api-docs-amsterdam-2017#cristiano
https://pronovix.com/event/api-docs-paris-2018#kathleen
- Here you can find some top-quality examples of developer portals:
https://devportalawards.org/winners
Note that the majority of the resources refer exclusively to API developer portals.
However, I believe we can - and should - think in more amibitious terms, and our solution should encompass more than just API documentation.
It would provide support to different types of users and developers, serving content tailored to different needs and use-cases.
I am willing to put work into this
- @skadinna (leading the effort, organizing content, testing tools, writing and updating docs)
- @ognarb (writing tools, helping with the organization, updating docs)
I am interested
- Lydia Pintscher (@lydia)