Editing the Wiki(s)

[wmarler]

Cheers,

Over the past week or so I've had a couple comments on various threads I started saying that it'd be welcome if I "contributed to the wiki," but it's not super clear which wiki I should contribute to, and it's not super easy to make the commits. 

First, which wiki do you want contributions to? There's the one on sub's github repo, https://github.com/sub3/NextPVR/wiki, and there's https://nextpvr.com/nwiki/pmwiki.php . Do ... do you want to maintain 2 wiki's for the same project? That sounds awful :-p. Yes, I'm offering my help here to consolidate the two.

Second, can you clean up your header links? On forums.nextpvr.com the Header link to "Wiki" points to https://github.com/sub3/NextPVR/wiki, but if you've somehow found yourself on https://nextpvr.com/nwiki/pmwiki.php, the header link to "Wiki" points to http://nextpvr.com/v4wiki/pmwiki.php, which is a broken link. Yes I'm offering help with that too, though I suspect you wouldn't want to give me the kind of access that'd require. 

Third, if you want contributions to https://nextpvr.com/nwiki/pmwiki.php ... how does one go about making them? I see a login page (https://www.nextpvr.com/nwiki/pmwiki.php...tion=login) but no way to create a login (and Forum login != wiki login). 

And last ... on https://github.com/sub3/NextPVR you say "create a github account, then PM me on the NextPVR forums (my account name is 'sub') , letting me know your github account name. I'll then add you to the list of collaborators with access to this repository." Ok, I can do that -- I would be more comfortable, at least initially, forking your repo and making pull requests, so you can look over my changes and approve/reject them ... maybe after a couple of submits that way I would feel like I deserved a place as a "contributor" on your repo. I suspect that I'm not the only one who has felt this way, and this has blocked more than one person from making a "small" change to the wiki. It's intimidating to have to PM sub for a 2-line wording change!

[sub]

First, which wiki do you want contributions to? There's the one on sub's github repo, https://github.com/sub3/NextPVR/wiki, and there's https://nextpvr.com/nwiki/pmwiki.php . Do ... do you want to maintain 2 wiki's for the same project? That sounds awful :-p. Yes, I'm offering my help here to consolidate the two.

https://github.com/sub3/NextPVR/wiki is the current wiki, and the only one we'll be maintaining going forward. The only created recently, and will solely focus on NextPVR v5, which is pretty much a new application with very little in common with older versions of the application.

https://nextpvr.com/nwiki/pmwiki.php was the old wiki, it has been very out of date for years, and only really relevant to NextPVR v4 and earlier. I was initially going to delete it, but decided to keep it around a little longer, in read only mode, in case there is any users of old versions that still need it. I'll probably remove it in 6-12 months.

Second, can you clean up your header links? On forums.nextpvr.com the Header link to "Wiki" points to https://github.com/sub3/NextPVR/wiki, but if you've somehow found yourself on https://nextpvr.com/nwiki/pmwiki.php, the header link to "Wiki" points to http://nextpvr.com/v4wiki/pmwiki.php, which is a broken link. Yes I'm offering help with that too, though I suspect you wouldn't want to give me the kind of access that'd require. 

The links should all point to https://github.com/sub3/NextPVR/wiki. I just did a quick check, and found a couple of places that still pointed to the old wiki. These have been updated to the new wiki.

Third, if you want contributions to https://nextpvr.com/nwiki/pmwiki.php ... how does one go about making them? I see a login page (https://www.nextpvr.com/nwiki/pmwiki.php...tion=login) but no way to create a login (and Forum login != wiki login). 

No, this will no longer be maintained, and is in read-only mode. It'll be entirely removed some time in the future.

And last ... on https://github.com/sub3/NextPVR you say "create a github account, then PM me on the NextPVR forums (my account name is 'sub') , letting me know your github account name. I'll then add you to the list of collaborators with access to this repository." Ok, I can do that -- I would be more comfortable, at least initially, forking your repo and making pull requests, so you can look over my changes and approve/reject them ... maybe after a couple of submits that way I would feel like I deserved a place as a "contributor" on your repo. I suspect that I'm not the only one who has felt this way, and this has blocked more than one person from making a "small" change to the wiki. It's intimidating to have to PM sub for a 2-line wording change!

That would totally have been my preference for how it works too, but unfortunately you don't seem to be able to do pull requests on github wiki repositories. If you can find some way to do that, let me know - or better yet, submit a pull request...

[wmarler]

Thanks!

I don't have a GitHub wiki in a repo myself, but https://help.github.com/en/github/buildi...-for-wikis says that you can open your Wiki to any GitHub user -- what about that?

[wmarler]

Hmmm, or maybe this? https://www.growingwiththeweb.com/2016/0...wikis.html

[sub]

I don't have a GitHub wiki in a repo myself, but https://help.github.com/en/github/buildi...-for-wikis says that you can open your Wiki to any GitHub user -- what about that?

I did see that option, but it sounded a bit too open to abuse for my liking.

[sub]

Hmmm, or maybe this? https://www.growingwiththeweb.com/2016/0...wikis.html

No table of contents etc, which sounds pretty limiting.

I have tempted to do something like that though, with the using the main repository for the wiki pages, but use some CI build process to auto convert markdown to html, and publish to some url like http://nextpvr.com/wiki. ie, so not actually using github as the viewer.

[wmarler]

No no, you read too fast . The drawbacks of "no automatic table of contents" and "no longer highly visible" etc come if you just move the documentation to the project repository. That's not the workaround being described -- the workaround is to clone the wiki, push it to a new repo (suffixed "-wiki" in his writeup) so that pull requests can be put out against THAT, then create a CI build that automates syncing between the two repo's -- the one which drives GitHub wiki, and the -wiki one. Then people submit pull requests to the "-wiki" repo.

[mvallevand]

One of the nice things about the current approach is being able to a submit minor change online without go to my PC and upload it, and then I just pull the change when convenient. With the PR approach, we'd have to wait for sub to approve the PR and we have to go through git hell resolving the inevitable conflicts that changes are going to cause.

Martin

[wmarler]

Yea, in two words, Documentation Sucks .

If you make it easy for anyone to make edits (anyone with a GitHub account can make changes) then you get spam.
If you make it too hard then documentation doesn't keep up with your feature set.
To make it easy to commit to but controlled takes work (mainly with setup -- practically speaking I don't think you'll run into many merge conflicts in a Wiki repo).
You could of course just document the code but then ... only programmers will see it.

It sounds like for now at least I'll be asking sub to authorize me as a contributor to the wiki, and we'll see how long I can keep my flame lit .

[Graham]

I would welcome an approval process ... Can't happen too soon.

Does it work to have a sub-folder in the wiki called ... "next" ... which contains all of the files in the wiki ... All changes are made to .md and .png files in the ... next ... folder.

Sub can monitor the Github history ... When he is content with the changes in the ... next ... folder ... He can run a script to change the links in all of the .md files to remove the string ... next/ ... (sed, perhaps) and copy the entire content of ... next ... into the wiki root folder.

I know little about github or sed or any of that so apologies if this is nuts.