## Description **Outdated, misleading, and duplicative documentation is worse than none.** It incentivizes people to ask internet forums or commercial LLMs — the former of which exposes them to negativity, abuse, and outdated information, while the latter offers sycophantic hallucinations with significant externalized costs. People with tasks just beyond their abilities often fail to achieve those tasks, or succeed in a fragile and sub-optimal manner after a lot of frustration. To be useful, documentation needs to be short, relevant, maintainable, unique, and translated. KDE's docs need attention to achieve those ideals: - User docs are split between https://docs.kde.org and https://userbase.kde.org, which look like they're from the 90s and are full of information that's years out of date or so obvious as to not be worth documenting. These aren't useful resources today. - Dev docs are split between https://develop.kde.org which is fantastic and highly useful, and https://techbase.kde.org which is moribund and mostly years out of date. - We also have https://community.kde.org, whose scope is encroached upon by tools like Gitlab and more dedicated documentation platforms, and content there also tends to drift towards being out of date. Content there is also English-only. This goal proposes to permanently address the situation in the following ways: ## What it will take - **Shift focus to tutorials.** People reading docs are goal-driven and want quick tutorials, not lectures about implementation details or abstract concepts. Retire irrelevant technical details and descriptions of the blindingly obvious. - **Insist on single sources of truth.** Duplicative documentation causes doubt; retire the userbase and techbase Wikis and ensure everything has a single logical home. - **Modernize infrastructure and tooling with Hugo or Sphinx.** These have a simpler translation story than Wikis; use the same styling as KDE's other websites; are backed by git repos to impose editorial oversight before publication; and use Markdown, HTML, and CSS for familiarity to basically all potential contributors. - **Reduce hierarchy and improve grouping.** Information in a hierarchy or web is hard to find; use "index" pages that organize all topics into logical groups based on use case not app, and link to all of them (i.e. what books have done for hundreds of years). - **Build a "Contributor Guide".** This would aim to eventually replace the patchwork of information on community.kde.org, with the goal to be as nice as https://handbook.gnome.org. ## How we know we succeeded - Each piece of information that somebody wants to look up has _one_ logical location in which it might plausibly be found. - All of our documentation is fully translated, or at least translatable. - Our software's user-facing documentation consists of an ever-growing assortment of useful short tutorials. - Our documentation gets better over time, rather than getting worse and more out of date, or even simply expanding without quality improvements. - As a result, online chatter starts to praise KDE's documentation, rather than criticizing it. ## Relevant links Some communication guidelines I agree with and have found useful, and that will help guide this effort: - https://quickfix.es/2020/10/the-baseline - https://www.opm.gov/information-management/plain-language - https://evaparish.com/blog/how-i-edit ## Champions - Nate Graham - Thiago Masato Costa Sueto - Joseph P. De Veaugh-Geiss The champions have individually been working in this general direction for years, for example migrating old dev docs to https://develop.kde.org/ and creating https://linux.kde.org/docs. Working together with community resources, they can turbo-charge their efforts and finally untangle the Gordian Knot of KDE documentation. ## Contributors ("I'm willing to put work into this") - Angel S - XXX - XXX ## Supporters ("I'm interested") - Akseli Lahtinen - Tracey Clark - Christoph Grüninger (e.g., Kile, QDoc) - XXX