Enabling the wiki for this repository

[gravitystorm]

I've been asked to enable the wiki component for this project, and in particular, open the permissions to allow anyone to update wiki pages.

However, I'm reluctant to do so, because I don't believe it is a good idea for managing this project. In my experience, wikis on github are rarely well maintained, and are anyway not as good a way to manage a project as using the other tools. Instead, I believe the best approach is to continue to use issues and pull requests to manage the individual changes, and long-lasting documentation should be kept under source control as we do now.

The specific reason given for enabling the wiki is to allow non-maintainers to manage the "list of good first issues", instead of having a meta-issue that only the original creator can update. I can see how that could be an improvement for this use-case, but only if you assume that a) having these meta todo lists is the best approach in the first place and b) that the lists cannot be stored as text documents in the repo and c) the lists should be maintained without the involvement of the maintainers e.g. without pull requests or other discussions. I disagree with all of these assumptions, so I find this specific reason not compelling at all for me to enable the wiki.

However, other people, in particular the other project maintainers, should be involved in deciding how this project is best managed. If there's a general consensus among the maintainers to enable the wiki, I'm happy to do so.

[imagico]

I am inclined to agree. We currently have the content of the repository - which is meant to represent consensus of the project maintainers, and the issues and their comments - which are individual opinions clearly attributed to individuals. While the desire to have something in between those is understandable it would also confuse responsibility and right now, while we often struggle developing consensus on style development itself i don't think we have either the resources or the social mechanisms to maintain a wiki and make sure its content actually represents the project.

Side note: I think we need to revisit the good first issues list - this is fine as a list of personal priorities of @Tomasz-W but as a list prominently shown on the issue tracker it is misleading to new contributors and therefore likely counterproductive. I think this is an excellent example of documentation that should represent consensus and not be free to edit based on individual preferences.

[matkoniecz]

The specific reason given for enabling the wiki is to allow non-maintainers to manage the "list of good first issues"

Why it can not be done within an issue or with issue labels, like other repos are doing? Or as text file in repository, maintained with PRs?

In my experience, wikis on github are rarely well maintained

I agree. There are multiple reasons for that, starting from lack of decent support for controlling edits (AFAIK even recent changes page is missing), lack of notifications etc.

[matthijsmelissen]

I agree with @gravitystorm .

[sommerluk]

I agree with the above comments.

[Adamant36]

One advantage of the wiki outside of the "good first issues" list is that it would for documentation of things that come up repeatedly, but might not be appropriate for their own file or entry in the database. Like docker and Kosmtik setup/errors. As it is the current contributing file assumes a certain amount of skills and
prerequisite that I just don't think are there for most people. I don't think its the appropriate place for basics either though, but they should be somewhere.

It would also be helpful if there was somewhere that document what certain parts of the code mean/do. I know there's general things about Carto code etc out there, but this style has its own unique quirks and ways of doing things.

Maintainability is an issue though, especially with keeping a list of open issues, but if things are kept more general it shouldn't be much of a problem.

[jeisenbe]

docker and Kosmtik setup/errors

I think we can document this in the docket.md file or a new troubleshooting.md file

document what certain parts of the code mean/do

It’s possibe to include a comment directly next to the line of code. But we could also consider creating a separate text file which describes the structure more generally.

[Adamant36]

I think we can document this in the docket.md file or a new troubleshooting.md file

That would work instead, I had the impression that the docker.md file was more specific. I guess it could be added as a section at the end or something though.

It’s possible to include a comment directly next to the line of code. But we could also consider creating a separate text file which describes the structure more generally.

There's some comments already. I feel like both files that the comments would be in are long enough in the tooth already though. Plus, that wouldn't allow for pictures or links. If this is a general, Swiss Army Knife style, there should something documenting what things do and how they can be adapted in detail. I don't think comments in code would serve that purpose.

I guess there could be a "how to adapt the style" file also, but then that's a lot of document files, it wouldn't be dynamic enough, and everything would have to be included through a separate PR that would have to be OKed by the maintainers before hand. Which seems obtuse and like a miss use of their time.

[matthijsmelissen]

I'm closing this issue as there seems no support for enabling the wiki.