QD5 Quick docs design improvement. #519
Labels
No labels
bug
Closed As
complete
Closed As
duplicate
Closed As
insufficient data
Closed As
moved
Closed As
not possible
Closed As
out of scope
Closed As
stale
good first issue
help wanted
improvement
needs changes
needs committer review
needs info
new change
Priority
awaiting triage
Priority
needs review
Priority
next meeting
Priority
waiting on assignee
Priority
waiting on external
No milestone
No project
No assignees
5 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference: Docs/quick-docs#519
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Based on point 3. in https://discussion.fedoraproject.org/t/project-quick-docs-improvement/44322
and the discussion here: https://discussion.fedoraproject.org/t/fedora-docs-design-work/40062
The idea would seem to be that the Quick Docs should be located to a new website (with a new UX design), would have tags added to them, and would be classified mostly as how-to guides, with other article types (such as reference-guide or explanation type) moved elsewhere.
This requirements would need refinement to produce acceptable acceptance criteria. This ticket is to track the work for the assignee.
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.
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.
Metadata Update from @hankuoffroad:
Metadata Update from @hankuoffroad:
Issue tagged with: good first issue
Metadata Update from @hankuoffroad:
Issue tagged with: help wanted
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'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?
Could we revisit this issue ticket related to the latest thread in Discourse?
https://discussion.fedoraproject.org/t/document-the-current-state-of-fedora-fragmentation/127499