I struggled a bit to find the HowTos for contributors. I think “Contribution Tools” indicates something different. Doesn’t it make sense to call the category “Contribution HowTos”, “HowTos for newcomer” or something like that? It contains only HowTos anyway
The naming is not optimal. But “Contribution Howtos” doesn’t fit either. Above the “Contribution Tools” their are contirbution howtos, how to contribut a new documentation, hot to contribute to existing documentation, etc. Maybe “Tool guides” may be better?
Yeah, my suggestions ain’t optimal either. However, “Tool guides” also needs some knowledge in advance to interpret it.
What about simply “HowTos for git, GitLab and Pagure”? That’s longer but clear.
Or get it one abstraction layer up. People have to click much before they see how easy it can be to use these tools for casual contributions (and that these tools are also for casual and not just full scale contributions).
One thing about interpretation: “Contributing a new documentation site” → I guess many people will assume “site” = “page”. This makes it look very complicated to add one page. We should not assume that people know the difference in advance. However, I think new sites/repos are not important very often and usually, when adding repos, this is discussed in the meeting in advance anyway. So we maybe should focus on other things at this place:
Therefore, suggestion: Switch
So, put the HowTos for casual users we want to reach with this page one abstraction layer before, and the contribution to release notes, adding new sites/repos and such put into an “advanced contributions” category or such?
Although, with the “advanced contribution” category in mind, maybe it makes sense to put the contribution to release notes also along the non-advanced contributions.
One question: What is “Contributing to existing documentation” intended for in contrast to the HowTos?
Still, I do not think there is a reason to postpone the merge! I think it can be published the way it is. After all, the changes we discuss have reached the level of pedantic trifles It’s a great page that serves our needs. Adjustments will come over time anyway.
But to be able to grasp the meaning, you already need to know about the relevance of git, etc. This is also a bit unfortunate at this point in the menu bar.
This is perhaps the best way comparatively.
We could completely omit the tools level and structure everything in a strictly action-oriented way.
Maybe something like
the GitLab tools (7-steps)- the gitlab tools (7-steps)
the pagure tool the pagure tool
systematic long term contributor
local Fedora authoring environment
for GitLab additionally WEB Interface
Release Notes Contributor
Reference to Fedora authoring environment
Completely new documentation area / domain
Reference to Fedora authoring environment
I didn’t think of a contrast, but of specific intention. routines and skills. My ideas is a “non-casual” contributor, probably committing to a special documentation area, e.g. Quick docs or an edition.
My idea was to describe the tools independently of the broader intention. But that’s probably not usefully. Someone, who contribute long term and systematically, will use a local environment or the Web interface, and that makes sense.
If we agree to restructure it that way, then we should do it soon, maybe again first in stg. If we wait too long we will have empty links in the search engines.
Makes sense! But given the limited amount of time we can invest in authoring and maintaining, maybe it makes sense to focus this as an overview and containing links to upstream Docs of GitLab and such. Every deeper “major” contribution needs talks in discussion threads or the meetings anyway. We can add that people could create a thread or let us know in the channel if they have already anything specific in mind to discuss it. So this would limit the work on this page.
A general suggestion, we should not force our contributors into roles. This can also create misperceptions of our institutions. So maybe generally replace “contributor” by “contributions”. One can engage in casual contributions here and there, and also in release notes contributions at other times. Hope that makes sense.
Systematic indeed makes a good point and a good distinction! Maybe this does not need “long term”: “Systematic contributions” ? Systematic can be also short term, which is still more sophisticated than a casual contribution. Or to make the “systematic” point clearer, “systematic/sophisticated contributions” ? Or “systematic/advanced contributions” ? However, the focus should be your “systematic” which makes the exact point. So “systematic contributions” on itself is maybe the best approach.
However, the question that remains is how to keep the barrier to the casual contributions (which is the potential entry route to Docs) as low as possible. So does it maybe make sense to not use a separated category for “casual”? The name of the guides can make the “casual” point themselves: “HowTo for *casual* contributions (for Pagure-based pages)”, “7 Step HowTo for *casual* contributions (for GitLab-based pages)”. I am a bit worrying that “casual contributions” does not make sense to people who are not yet engaged with Docs, making them omit the category that is explicitly intended for them. Yet, my argument is as probabilistic as any other.