Hmmm, we can’t compare one documentation type/platform with others, can we? Each one serves different purpose. Wiki doesn’t seem to flourish as a documentation platform in Fedora. Some working groups have a plan to retire wiki entirely and move to Docs.
I didn’t list up shortcomings of Pagure Web UI as a reason for centralization of Git forge. Pagure is a best fit for CLI workflow. Web UI is rather pristine. Some of experienced authors prefer Pagure to GitLab.
Now I’m switching my documentation writing workflow to CLI completely, and Pagure suits my workflow.
For what it’s worth, I thought I’d chime in just to add another point of view, in the hopes my views might intrigue “stakeholders”.
Let me start by saying I’ve only been silently following this thread because I really appreciate any and all efforts of improving the docs with Fedora.
In the short while I’ve been using Fedora, I’ve had my issues with documentation, eg:
(note for example my attempt of finding more/better/accurate information outside Fedora Docs, with pykickstart docs)
Platform Fragmentation (especially of documentation!!) feels terrible on Fedora…
As a (new) user, I wouldn’t know where to look.
As a (potential) contributor, I don’t know where to act.
So many platforms that serve “different purpose” is 100% not a good thing.
Elsewhere, discussing Fedora first impressions I’ve stated:
So many different domains and platforms for discussions, documentation, issues,
bugs, packages, meetings, stats. I guarantee new users will be intimidated in their effort to keep well informed.
I stand by that statement.
I might have said harsher things too, but I intentionally omit them here, because the intention of this post is not to get argumentative, but rather to offer some (hopefully) constructive criticism.
So, I don’t see why comparing documentation type/platform would be unfair in the context of that previous post.
If there is information that is/gets duplicated across platforms, then there is information that is either misplaced or redundant.
And I don’t have any opinionated say in regards to the tools used — I’ll leave that to those of you who actively strive to make the end product better for all of us — but the fact that me or others aren’t actively contributing will probably remain so for as long as the bigger picture remains so confusing…
As far as I remember,
Wiki used to be a source of knowledge base across many working groups before 2018. Check this Magazine article “Fedora’s Documentation Website has been overhauled”. Many wiki articles were converted to Docs using wiki conversion script. Wiki vs Docs is best explained in this thread.
Docs: Documentation sites were incorporated into Antora static site generator that combines different Git forge. The Fedora Project respects a decision of working groups/SIGs. Since 2022, many working groups/SIGs moved to GitLab. Still, it is confusing for new contributors why one has to work on different Git forges.
Docs articles are maintained, peer-reviewed, and version-controlled. It requires certain routines and processes that are natural for developers. For those who are not familiar with it, there is a learning curve that worth learning the ropes.
The Fedora Magazine is, by definition, “a website that hosts promotional articles and short guides”. Although some of short guides are very comprehensive and self-containing, the content that needs updating is not suitable. I don’t see overlap between Docs and Magazine in its inception. But some how-to articles in the Magazine can be found also in Docs, which looks duplicated.
Fedora CommBlog: It doesn’t publish knowledge articles. What is being duplicated?
And other platforms - even Fedora moderated accounts do not publlsh knowledge articles.
Discourse: we have been discussing this topic on other threads. I recall you will be running a poll.
Matrix/mailing lists: it is irrelevant here as a knowledge platform.
As @pboy shared his view on tool vs content on other thread, platform integration and preference on tools are not related to quantity and quality of documentation.
I grew out of confusion and duplication. I learned a ton from challenges faced by Docs team. Help make us less confused and dedup content. I did my part.
I’m only stating that, for example, some platforms cited by @boredsquirrel are not established as knowledge portal.
Yes, some topics are over documented across different Docs pages, discourse and the Magazine. Others are in poor state (untouched for many years).
Some will wither away as a knowledge platform (like wiki) in Fedora. More and more working groups are moving to GitLab. Release notes are migrated to GitLab.
We do this by stage, preparations and consensus. No one stands up and says ‘unify all platforms’.
We are short of resources. Help us.
We also share experience and knowledge by Docs workshop and other events.
Some portion of the duplication comes from people running into the limitations of previous tools and trying to unify what existed already under a newer/better tool. The problem is that the old content needs to stay up but keeps getting added to AND the new team usually run out of energy.
A good portion of the older documentation was built around the idea that Red Hat would provide a core of documents and others would join in. At first these initiatives would start with a large number of volunteers and then eventually run into ‘no volunteers’ due to personality conflicts or conflicts of direction. Then there would be reorganizations inside of Red Hat which would change the teams focus and documentation would drift off.
In the end, technical documentation is very very hard. I would put it harder than coding as developers usually don’t find they can document well what they are doing without rewriting what they had done to ‘fix’ something. Having volunteers doing it is great, but it comes with the caveat that volunteers get to choose the tools they use. If they don’t want to write asciidoc but you tell them they have to… they go somewhere else. If they don’t want to write stuff in a wiki, they will go somewhere else… etc. Which means that over time you end up with a lot of little sites spread all over.
Great if you could list up top priority areas of de-duplication and effort required.
You took an example of Fedora Atomic Desktops and @siosm already responded with a plan on other thread.
De-duplication, for example, could be;
Consolidation of pages, repos
Archiving
Agree on content category by each platform: For example, we need to avoid a situation where a contributor publishes an article at platform A[1] because the person was so fed up with platform B / process / people.
Or if you have a better idea, feel free to share and let’s get buy-ins from other contributors.
I believe we need to create a sort of funnel of wish-list followed by problem statement, and group them by;
Doable and tangible: could be done by a single team or small group of people.
Must-haves but requires resources across many teams
Long shot: reaching for the stars
Ideation, peer review and publication are quick. Process is efficient and well documented. There are regular long-term contributors around. Atmosphere is good. No need for weekly meeting ↩︎
There are many ways to tackle and improve situations, but I’m not sure showing dirty laundry on high traffic site would encourage participation and goodwill. If you don’t know overall problems or can’t sum it up in constructive way, I don’t think we will get buy in from our colleagues.
I’m not saying this because I don’t see a problem, but I don’t want to boil the ocean for something I can’t influence.
From the top of my head (might come up with more later):
The wiki landing page should only consist of information that communicates its purpose and then only addresses contributors according to the context you kindly offered previously in this conversation.
The only user facing information on it should be:
Explain that this page is addressing contributors. If there is need to expand further than already included in the “#This Wiki” section, then very briefly summarize changes in the thread you linked above.
Redirect all Users to Docs. If information currently on Wiki landing page is important, include it there (Docs) instead.
Better contributor-facing content for the landing page could be:
Recently updated pages
Pages flagged out-of-date that could use contributor attention to be brought up to speed.
Is Fedora Magazine part of the Project? If so, move it under the .fedoraproject.org domain.
If the answer on #2 is yes, then it would be ideal to “widen” the “news-worthy” umbrella to include both Fedora Magazine AND community blog. It would also be more visually pleasant to unify the visual identity of such domains and everything else (eg follow the style/look-and-feel of the Fedora Project Landing Page. If clear separation is needed, it could be applied to site-level/category separation.
That’s right and I wholeheartedly agree with ‘preventing loss of knowledge’.
Make it ‘convenient’ to contribute.
I believe there should a boundary to what we must do and what not, to manage expectations. In Fedora package source, there are several thousands RPM packages. Do available tools mean everything or packaged maintained by Fedora Project or Red Hat?
Often I hear “go to upstream” by long-term contributors, which I learned the hard way. Unless the user knows problems are caused by a single application of upstream, “go to upstream” is sort of gatekeeping and barriers.
There seems to be a high level of fragmentation and duplication also inside the Docs.
Quick Docs seems to be one of the most comprehensive documentation “modules”[1], so the name doesn’t do it justice.
Then we have Fedora Workstation, which is extremely modest regarding the information provided, and mostly covered by Quick Docs. Quick Docs is more or less the documentation for Fedora Workstation[2].
The Spins and Labs module is a just a page with links to the corresponding presentation and download pages on Fedora’s main website.
I would love to see most of these modules (the ones within the “User Documentation” section) under one umbrella, with all the modules (Workstation, Server, CoreOS, Atomic Desktops, Spins etc) as main chapters within the same documentation.
I imagine this is hard, given that each of these docs are maintained by different WGs/SIGs, but I guess it is doable, as Antora does a pretty good job of presenting these pages in a similar way from a UX perspective[3].
" The one that you’re most likely interested in, and the one that we’ll be focusing on, is Fedora Workstation" - quote from the Getting Started with Fedora page within Quick Docs. ↩︎