There are 80 open PRs for Documentation edits, from recent to past. Perhaps some past ones are no longer applicable but many recent ones certainly are. How can we get the PRs merged sooner? Are they only evaluated/considered during each Hugo binary update?
https://github.com/gohugoio/hugoDocs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc
It’s a bit of a problem with Hugo (and many other Open Source projects, to be fair), many pull requests are not handled. I have a 2019 pull request to Duplicati that’s still pending… needless to say, I didn’t waste time making other commits to Duplicati.
From what I understood almost all the work is mainly on @bep 's shoulders, but he’s just one person, and HUGO is not even his full time job (i.e., he doesn’t get paid for all the work he’s doing).
I have a feature that I desperately need in Hugo, the Wikimedia internal links [ ], I did a pull request and I’m waiting, in the meantime I’m using my personally patched version of Hugo version 0.97.
I would like to help, not only with my pull request but also with Hugo, but I don’t know how. I don’t know how the other big open source projects managed to move forward when they reached a certain momentum.
I know that some (like Carbon language) laid out an explicit roadmap and some goals ( carbon-lang/roadmap.md at trunk · carbon-language/carbon-lang · GitHub )
Always at Carbon, they set up a collaboration system that gives some sort of coordination such as the weekly syncs, the open discussions which are unstructured meeting slots used for discussing proposals, tooling, and other Carbon topics based on who attends , and proposals for major changes such as new features that are assigned to a internal “lead” (i.e. a person in the Carbon working group)
Not that HUGO needs to go that way, Carbon wants to replace C++ with a new programming language, and that requires a lot of formalism, we don’t want to do that, but maybe there are ways to streamline HUGO’s development. I don’t think that HUGO is the only project that went from version 0.01beta to a big project with thousands of users and many contributors as it is now.
So, ideas?
The other issue with open source projects, especially those by a sole dev, is that most of the updates you get are what the led dev wants, or has in mind, and the community requests come second in the hierarchy of needs. I good solutions in the pending requests, and patch my way through everything else.
To add more, I checked the stats and there are as many new users of Hugo as those who abandon it for other projects. The docs are the biggest complaint from users.
There was some continuous activity going on early this year, but all that cooled off from around April. It also appears one of the moderators has left.
@mayr I agree that the docs are terrible, I spent many hours trying to decode what was written - and to guess what was not written but should have.
As of now, I have pull request #1744 pending. I’m ready to commit some time to a working group devoted to improve the documentation, but given my previous Duplicati experience, I would like to know that my work is useful and relevant also to the HUGO “maintainers”.
What about setting up a few sprints for the documentation? For example, end of September, end of October and end of November.
We group together the ones of us that have already made a pull request (or are willing to make some) and we start to cross-check each other’s work.
As we can do very little by ourselves, it would be nice if one or more of the official “maintainers” of HUGO join in
I saw that @jmooring from time to time posts commits to the Hugo Docs, maybe he would like to join the conversation
I see this thread, and I understand, but I currently don’t have time to look into it (and dont’t misunderstand, I’m still putting lots of thoughs/work into Hugo, I’m just having doing so wearing blinder to get some real work done).
I will eventually come back to this.
@bep I don’t speak for anyone but myself. The path you’ve taken Hugo has been incredible and I think even more so given that it’s mainly just you… but the other side of that coin is… it’s just you and that seems pretty lonely on a high profile project like Hugo. Are there any other Go developers in the community that can start to distribute the load?
I think the Hugo software is fantastic. There is constant development and bugs generally get addressed very quickly (depends on the bug of course). Honestly no complaints there. Documentation is the biggest roadblock, and that’s not a new observation of course. I decided instead of constantly bitching about it in the forums (which themselves are a MASSIVE asset to Hugo), when something in the docs was insufficiently described, or I learned something that I couldn’t have learned from the docs, I go and make a PR for that so the next person won’t have the same question.
I feel if everyone (not gonna happen of course) were to do this, to make something that was not explained or unclear in the docs to become well explained and clear, every time they learned something from the forum or from personal experience, the docs would steadily become better.
This thread, or at least for my part, is not at all a pile-on for “why aren’t you doing more?!” but that the need is there and I want to help were I am best able.
And now with the web-based vscode instance made from a repo fork, it’s beyond easy to make edits.
Just as an example, today I saw this on the documentation:
No html displayed for the Instagram shortcode Shortcodes | Hugo. Easy to fix, but if I come to believe that my commit will be ignored for the next few months, I don’t bother.
We can not only make PRs, but we can also review the PRs made by others, a sort of pre-screening among us. What do you think about an “agreement” with some of us that once in a while (once a month maybe?) you set aside some time to batch-review and merge the pull requests that were already pre-screened by us? Of course with some feedback, this is ok, this is not ok for reason A and B, so we can improve. If we’re good at it, in a couple of months we should be able to digest all the backlog without putting too much pressure on you (and without granting to anybody else the permissions on the Hugo repositories)
