Blaise Pabon kirjoitti 29.11.2021 klo 18.38:
Hi Otto
On Sat, Nov 27, 2021 at 7:17 AM Otto Urpelainen <oturpe@xxxxxx> wrote:
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?
Yes, you're correct.
I'm sorry I conflated the content question with the toolchain discussion.
Content: How to become a packager (checklist / decision tree)
It might help to step through the process and enrich the new docs.
Ah yes, the wiki Join page had a flowchart about adding a new package. I
did not bring it over to the new docs, because it had issues:
1. Joining the Package Maintainers is not (only) about adding a new
package, but starting the article with the diagram gave exactly that
impression.
2. There was no caption or explanation, so it was quite unclear what the
diagram was about. Probably because the surrounding text was living its
own life, but the diagram remained in its original form.
I agree, such diagrams are good to have. Removing it with no replacement
was a step backwards.
The old diagram could be meaningfully imported to "New Package Process
for New Contributors", maybe also to "Package Review Process", I think.
ToolChain: Antora/Pagure are more aligned with the code development cycle.
Sphinx and Mediawiki are more aligned with describing practices and
cross-references.
Before I implemented the move from wiki to docs.fp.o, I did bring the
topic up in the devel list. There were some people who thought that this
was a bad idea. Others were supportive.
Personally, I think the system over at docs.fp.o has many advantages:
1. It is easier to make the large changes with a proper editor locally.
2. Git allows atomic commits spanning multiple pages.
3. Pull requests allow easily asking for feedback and iterating on that
before going live.
4. It is easy to put things in categories and hierarchies at docs.fp.o,
whereas in the extreme free structure of wiki caused materials of
different nature become mixed up. The situation here was so bad, that
during the move, no less than 5 FESCo policies [1,2,3,4,5] were added
the to the FESCo docs. These were hiding in the wiki, mixed with other
material in various degrees, editable by anyone without FESCo even
getting notified that policies they are supposed to have define were
being altered.
[1]: https://pagure.io/fesco/fesco-docs/pull-request/43
[2]: https://pagure.io/fesco/fesco-docs/pull-request/44
[3]: https://pagure.io/fesco/fesco-docs/pull-request/45
[4]: https://pagure.io/fesco/fesco-docs/pull-request/46
[5]: https://pagure.io/fesco/fesco-docs/pull-request/49
Still, the greatest motivation for choosing docs.fp.o was that that is
the current docs solution of Fedora. Choosing anything else would make
the Package Maintainer Docs an outlier, and would prevent taking
advantage of any available tooling for docs. For example, we now have
online editing, localization and automatic periodic deployment without
having to work on them separately (though I admit, I have never tried
the former two, so I do not know how well they work in practice, if at all).
Perhaps there would be an even better solution for docs.fp.o, I do not
know. As I see it, it is out of scope for the Package Maintainer Docs,
which should just use what is in use distro-wide.
I would be happy to make myself useful if you have any suggestions.
The last time I just jumped in to try to do things and that didn't work
well.
I am not sure what happened, but I am sad to hear that the end result
was not good even if you had good intentions.
Be that as it may, the Package Maintainer Docs welcome contributions.
Since you already mentioned the lack of checklists and decision charts,
adding such where they are needed would be great. I noticed in the links
you sent earlier that you have some ideas how to add diagrams in
maintainable way, having something else that just uploading bitmaps
would be great, even if update requires some manual steps.
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
