Who is the "assignee" here? (you :) ?)

@ankursinha whoever wants to take it, or has time to take it. It isn't necessarily earmarked for me. I just created this ticket based on the linked discussion.

Cool, let's leave it for the moment and see how things go.

I suppose, we must first try to get a design and UX expert onboard.

I suppose, we must first try to get a design and UX expert onboard.

Ongoing improvements are underway for Docs UI. The latest MR is Table, caption styling fixes made by @ferdnyc

https://gitlab.com/fedora/docs/docs-website/ui-bundle/-/merge_requests/7#note_1362916238

What design / UX improvements were defined? It is right time to get the requirements.

I have quite a bit more queued up as well, upstream imports that just need to be adapted to the Docs site (primarily the dark-mode styling) to be compatible.

I read @aday 's Discourse post... personally, I'm really reluctant to fracture our documentation further. I get the idea behind the internal/external documentation split, and I think that makes a lot of sense actually, but having a separate site that's merely organized differently is one thing. Having a completely separate backend that uses a completely different documentation format is another thing entirely.

I'm also loathe to switch streams to another syntax for documentation so soon (relatively) after the switch from MediaWiki to Asciidoc. (We're still scrubbing Wikitext out of the packaging guidelines.) Especially if the switch is to a language like MarkDown that... honestly, just kinda sucks.

MarkDown is fine, for simple needs like... well, like writing these Pagure comments. It's all the markup anyone needs for simple communication. But IMHO it's far too limited to produce good documentation; it can be extended by adding syntax, but then there has to be some way to inform people of what enhancements are available, and to teach them the syntax specific to the platform, which defeats the whole purpose of switching.

Asciidoctor can support MarkDown-style markup for simple things. (I think it "just works", actually, but if not it's an option that could be enabled.) But its own markup offers significantly more advanced capabilities (ones we do make use of) as standard elements of the language syntax. Which means (a) authors can learn them from the upstream documentation, and (b) once someone knows the syntax, they know it everywhere.

That's why I've been pushing so hard to flesh out Docs' support for the full Asciidoctor featureset, because authors should be able to use all the syntax of the language without wondering what's actually supported by Docs.

(On the "still scrubbing wikitext out of the packaging guidelines" — yes, it's been years and it's kind of amazing that's still going on, but it's because nobody really wants to put in the work. I keep hearing that the barrier to writing documentation is the syntax, or the VCS system, or the organization. That's crap. When are people going to accept that the barrier to writing documentation is simply that nobody likes writing documentation?)

@ferdnyc thanks for sharing your thoughts and support on dark mode styling.

I read @aday 's Discourse post... personally, I'm really reluctant to fracture our documentation further. I get the idea behind the internal/external documentation split, and I think that makes a lot of sense actually, but having a separate site that's merely organized differently is one thing. Having a completely separate backend that uses a completely different documentation format is another thing entirely.

I'm with you on that. The whole point on design revamp is evolved around aesthetics over form. Considering fast-paced changes and workload on the website contributors, I think Docs team needs to focus on design principles associated with usability, a11y as a priority.

Regarding the AsciiDoc markup, Docs team slowly adopts more standard templates, attributes to make the docs structure consistently.

Wiki conversion continues as a part of content reuse.

Please find the latest issue I created about content review cycle.

https://pagure.io/fedora-docs/quick-docs/issue/598

We just need more reviewers. Arch wiki has 400 contributors for maintaining documentation only.

I dipped my toes to Docs in December 2022. We are working to recruit more writers and reviewers from existing pool and new prospective members. Let's stash pessimistic thoughts over barrier and unwillingness to write documentation. We need to show paths and talk about experience.

Do we value good-quality documentation, and those who write it? Yes.

@pboy could the Docs intern revisit this?