I’m looking to improve the Workstation Working Group’s online presence. Currently we are primarily located on the wiki, where we have low visibility. I was recently told that the wiki is old news, and that docs.fedoraproject.org is the new home for “internal” Fedora project pages. However, I haven’t been able to find any information about this. Should teams be migrating to the docs site? Is there a plan to retire or move away from the wiki?
I have some separate questions about the design of docs.fedoraproject.org, but am unsure where to direct them. The docs mailing list seems a bit dead, and I’ve been unable to find the project that’s responsible for the docs site itself.
information that’s either user facing or internal to SIGs but does not change frequently: docs
It’s up to SIGs/Teams however—if folks prefer using the wiki that’s fine, but user-facing docs should go to the docs so that it’s all in one place. (We want to save users from getting lost in the wiki)
The docs team isn’t as well structured at the moment (no regular meetings etc.), but plenty of folks are working on things. For example, the quick-docs repo is seeing regular activity, and there are tweaks being made under the hood all the time. I guess filing tickets on the docs pagure project is the best way of getting in touch with those managing the infra etc.
That’s pretty good, but I’d characterize it slightly differently:
short-term information goes into the wiki
long-term information goes into docs
That said, there’s a lot of inconsistency because there’s a lot of effort required to migrate docs and the Council has no desire to force people to move.
The wiki is unlikely to go away, but in most cases, Including what @aday describes, docs are a better choice.
Thanks @ankursinha and @bcotton ! Do you have examples of the two types of content that you have in mind? I’m struggling to imagine examples of frequently changing information that might be appropriate for a wiki.
One of the goals here is contributor capture which is its own can of worms. Currently getfedora.org directs to the join Fedora page on the wiki, but it’s huge and doesn’t seem to receive many updates. There’s so much stale, out of date information on there… that’s part of the reason I wonder about the future of the wiki.
The wiki us used more as a reporting/scratch pad in this case. Most of the general content for teams is information on on-boarding and SOPs etc., which are relatively long term and so are slowly being moved to docs.
Yeh, that wiki page is a nightmare… I think the websites are to be refreshed (I can’t remember where I got this info somehow). So I expect all of this will be updated then. I’d personally prefer that any links to joining the community point here:
where folks can see the orgchart etc. and contact us at the Join SIG if they need to:
Right, the distinction there is more between pages that have long-standing relevance, and those that are only used for short periods of time. And if you differentiate between the wiki and the docs site in that way, the wiki is left with virtually no content remaining (not necessarily a bad thing, but worth being explicit about).
If we do consolidate around the docs site for contributor onboarding, that would certainly make things simpler for me!
That said, if we do do that, then something has to be done with all old content on the wiki. If it’s just left sitting there then it will cause all kinds of problems for people. In that regard, moving to new infrastructure doesn’t necessarily solve the problem of old, stale content - we still need to deal with it.
What would be really helpful from my perspective would be to have a plan and guidelines for internal project “documentation”. I could be helping out as I go, but as it is I’ve spent a fair amount of time just figuring out what’s what.
That’s out of scope for the website refresh work. I’d suggest redirecting that old wiki pages to the docs. You can do that with: {{#fedoradocs: https://docs.fedoraproject.org/en-US/project/join/}}
I meant changing the link on getfedora.org to point to docs, not updating the wiki page on Join. I don’t know what is to be done with the existing wiki page on Join but it contains a lot of detailed info that we may not want to lose completely. So it just stays there for the time being until someone comes up with the courage to work on it
Yeh, but that needs quite a bit of time and from the looks of it we don’t have the resources to clean up the wiki. Just changing all mentions of Freenode to Libera seems to be a daunting task in itself:
Someone in my position needs to know what to do with the old content they are maintaining, and how to integrate with the new docs site. Without a plan and guidance the docs situation becomes a roadblock for individual contributors.
Dead documentation and broken project navigation has a significant negative impact on an open source project. Can we afford not to do anything about this?
Resources in open source aren’t fungible. If we had guidance for how to deal with stale content, then we might be surprised at who might step forward to do the work.
I could spend a bit of time on this, if it helps unblock the process for other contributors who are in a similar position to me.
I looked and looked for that page! This is actually a great example of the problems around the docs at the moment. Before starting this thread, I spent some time searching for docs on the docs site itself. I couldn’t find anything to do with docs on the docs site itself (is it accessible from the homepage?) When When that failed, I searched for Fedora docs team, which gave me their wiki page, which doesn’t say anything about their presence on the docs page, and doesn’t redirect there.
It sounds like a Mission Impossible to update old documents and old links.
To make things simpler moving forward, how about setting a cut over line, such that for documents after a particular version will only be published in docs.fp.o ?
For example. once Fedora 35 is branched:
new documents for the Rawhide (F36) will be on docs.fp.o only
relevant documents for F35 will be consolidated to docs.fp.o as much as possible (may be only publish the delta from F34 to quick-docs)
I would definitely welcome your help, Allan! One thing that should finally be coming is search, which the original plan assumed we would have very quickly. The current front page is just a placeholder that has grown large, and wasn’t really planned. Once search is in place I think it should be redesigned to be search-centric.
I’m open to the Council taking a more aggressive position here as part of an intentional effort.
I’m not sure how impossible it is, if you are somewhat ruthless and have clear guidelines. Most of it would be marking pages as obsolete and/or deleting them. In some respects the main thing it requires is for someone to feel confident enough in doing it, which somewhat makes it an empowerment question.
But yes, you’re right that a broader wholesale move away from the wiki might be more practical!
Of course it will not be 100% impossible given unlimited time.
If we set a time line for the next 3 releases - that is less than 18 months, then it can stretch the human resource too thin to handle old documents and new documents in parallel.
If the community can agree to have new version on docs.dp.o only, then:
it will be easier to recruit new documentation contributors, as the environment is simpler
once more new contributors are on board, experienced document maintainers can focus on what / how to do with the old archives
If there is no decision, then the issues will only got bigger over time - and ultimately will need more efforts to tackle.
I wonder if it would be good to add some Disallow: lines to https://docs.fedoraproject.org/robots.txt to keep some of the older content from showing up in search results? For example:
Intentional effort sounds great to me. I think the main thing is to set the direction, provide guidance for the migration, and have a plan for retiring the parts of the wiki that are no longer helpful (whether it’s removing obsolete material, flagging it, or taking the site down entirely).
