Blaise Pabon kirjoitti 26.11.2021 klo 18.01:
Hi Otto,
On Thu, Nov 25, 2021 at 2:27 AM Otto Urpelainen <oturpe@xxxxxx> wrote:
Blaise Pabon kirjoitti 25.11.2021 klo 5.43:
<snip>
When the docs were migrated, the intent was, of course, to make them
better, not worse. If things have regressed in some way, I would like to
fix them. Could you be more specific, in what ways the new docs less
useful? Is there some particular content in the retired wiki pages that
is not available at docs.fp.o, or what is the problem?
TL;DR: We could mitigate a pervasive "works-on-my-machine" anti-pattern
with a few simple measures.
(Two years earlier....)
After 30 years at the fringe of Open Source, I decided to throw myself into
the Fedora community and find ways to contribute. I observed a few common
anti-patterns. "works-on-my-machine" happens when there is no distinction
between internal and external behavior. So, a developer has no guidance on
how to describe {{ process | artifact }} to an external stakeholder.
I am not sure what you are referring to here. I suspect that I
misunderstood what you were referring to with "older docs" and "new
docs". I thought what you referred as "new docs" were the current
Package Maintainer Docs [1] and "older docs" were the Fedora Wiki pages
that they were imported from (there is a list of those at [2]). I do not
think the move between the two changed anything related to
"works-on-my-machine anti-pattern" — unless you are talking about
tooling, not content.
[1]: https://docs.fedoraproject.org/en-US/package-maintainers/
[2]:
https://github.com/iagorubio/fedora-docs/blob/main/issue20/package-maintainer-imports.txt
Looking at the current state, one thing I notice it that currently, the
"Joining the Package Maintainers" page barely mentions sponsorship. This
is fallout from trying to make that page sound less like you have to
submit a new package to join, previously it was discussed in the "Adding
a new package" section, which is now a separate page. I will add a note
with a link in the Joining page summary, so that part is clear from the
outset.
These links include examples.
Docs community contribution hackfest (discussion)
<https://discussion.fedoraproject.org/t/fedora-docs-community-contribution-hack-fest-with-user-communities/503/23>
Write contributing guidelines in markup file and make them more visible in
a project <https://pagure.io/pagure/issue/4131>
[RFE] Expand the README to include "How to provide feedback"
<https://pagure.io/pagure/issue/4125>
The first link is about other docs than the Package Maintainer Docs,
with some critical comments from you about the use of Antora in
docs.fp.o. The latter two are about Pagure. So if I understand
correctly, when you say that the older docs were better, you did not
mean the content, but that managing the docs with MediaWiki in the
Fedora Wiki was better than the current Antora and Pagure based approach
that used at docs.fp.o. Did I get that right?
Otto
_______________________________________________
devel mailing list -- devel@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to devel-leave@xxxxxxxxxxxxxxxxxxxxxxx
Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/
List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines
List Archives: https://lists.fedoraproject.org/archives/list/devel@xxxxxxxxxxxxxxxxxxxxxxx
Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure
