"it would be more useful to link to the non-raw pages on github ..."

[raiph]

TL;DR:

moritz: "it would be more useful to link to the non-raw pages on github ..."

paultcochrane: "To be honest, I think so too. ..."

Aiui it's an easy change; shall we do it?

---

When fixing typos and the like in other projects shared on github I've generally been able to just click a pencil icon, make an edit, and click the save button and then my changes will appear live in a short while (or, if I don't have commit rights, I click another few buttons to create a PR). This encourages me to make edits.

In an old closed issue the last two comments were Moritz's "it would be more useful to link to the non-raw pages on github" and Paul's agreement: "To be honest, I think so too."

There are a variety of problems of course. Paul mentions one. Other factors to consider include that it might be considered better to push folk to read the contributing doc before they do a PR.

Based on my current understanding that this is an easy-to-apply change, I agree with Moritz and Paul that, all things considered:

it would be more useful to link to the non-raw pages on github

[coke]

To my way of thinking, if someone has commit bits, it is not that unreasonable for them to use a local checkout to fix the issue, or to be able to search the repo to find the bug.

IMO, this would be nice to have, but it's a lot of work for little payoff.

[raiph]

a lot of work

I had thought this was a one line change. If it's more complicated than just altering the footer link as suggested by Moritz and Paul then I think I've misunderstood what they were suggesting and we can just close this issue. Feel free to do so.

for little payoff

You may be underestimating the value of making things easy for newbies.

I've fixed stuff from typos to writing the original of a doc page by sticking to use of the Github UI. Perhaps I'm unique but I instead think there's a class of newbies who are willing to contribute to Perl 6 docs but prefer to use the web UI and avoid learning the git CLI.

if someone has commit bits

Having or not having a commit bit made zero difference to my process.

If you prefer, just assume this ticket is about someone who does not have a commit bit. And if your answer to that is that everyone gets a commit bit, then please remember that giving someone a commit bit doesn't actually change what that person knows.

[jbolden1517]

BTW read the dicussion on the #1212. FWIW as a newbie. Strongly think the click and edit approach is a good one. The way Wikipedia (in the old days) got committers was someone knew a single date, or had a reference for a single point. Or could write a good paragraph or... They made minor changes and from there worked up to do articles. Then from there worked up to doing infrastructure work and supporting. You want the barrier to first commit to be as low as possible.

Remember that the Perl6 community is right now about to change from people who are designing a computer language to people who are using a computer language for many thousands of verticals. The documentation is going to want to evolve to get highly specific about: how do I do X-domain specific thing in Perl6; which is a different type of author from the early round of documentation of how does Perl6 handle Y-computer language concept.

[samcv]

Github doesn't yet have Pod6 support so I don't think we have to worry about its pod rendering having issues.

Regardless. I think a good stopgap would be to have a guide to tell people, this is how you fork the repo. then click here and click here. Give them a step by step to fork and make a Pull Request, assuming they have never used Github before. Would be a good stopgap.

If the p6doc page linked to the non-raw github page when one is available, folk could follow a "simple click and edit approach".

I am all for this.

We could have a link to information about how to contribute in the description bar here:

Perl 6 documentation (tools and docs) https://doc.perl6.org/ | To help make a change see here:...

[raiph]

Github doesn't yet have Pod6 support so I don't think we have to worry about its pod rendering having issues.

I'm struggling to recall what I found when I first looked into this a couple years ago (the time of the prior now closed issue with Moritz et al's comments) but I think it went something like this:

• We stored p6doc .pod files on github;
• When one viewed them on github it rendered them as if they were Perl 5 POD;
• So they typically displayed as some weird looking text ending in a highly confusing error message;
• So we linked to the raw page;
• Which is perhaps a little less confusing but still confusing nonetheless.

Or something like that.

I think a good stopgap would be to have a guide

Fwiw, I just followed existing github guides to learn that. I found it easy to follow these guides.

Indeed, that's another reason I raised this issue again. Not only is it -Ofun to edit p6doc in this sense but, also, following the existing guides leads to failure and that's likely to be a serious psychological obstacle, perhaps determining of their (non-involvement), if folk (incorrectly, of course) surmise and assume that the Perl 6 project is at fault.

[AlexDaniel]

See also #167

[ghost]

This remind me to Mono's documenation page where there is an edit link to the page - http://www.mono-project.com/docs/tools+libraries/tools/monodoc/generating-documentation/

[AlexDaniel]

By the way, there's nothing hard about this issue anymore. Just change it to a non-raw link, that's it. Possibly make it more visible.

Previously github attempted to do a preview of these pages thinking that they are perl5 pod, nowadays we have .pod6 extension on most files. If not all files have .pod6 extension, then it should be fixed.

It's easy to go from a non-raw link to a raw link (just click the button), but it's hard to go back (edit the url!), so we're not losing anything.

Sure, we can then think about implementing the click-and-edit something, or whatever… But for now this first particular step is LTA.

[raiph]

Just change it to a non-raw link, that's it. Possibly make it more visible. ... It's easy to go from a non-raw link to a raw link (just click the button), but it's hard to go back (edit the url!), so we're not losing anything.

\o/ Thank you. This is what I was trying to say/suggest from the start. :)

Sure, we can then think about implementing the click-and-edit something, or whatever…

/o\ This has got to be a remnant of folks' misinterpretation of what I was suggesting in the first place, right? All I was suggesting was to link to a non-raw page so that someone can then click (the pencil icon) and edit.

AlexDaniel added LHF

I considered just going ahead and trying to make the change myself before I opened this issue. But I didn't have the relevant p6doc generation scripts installed somewhere and I wondered if there was more to the issue than I was seeing. Now I feel the latter has been eliminated I'm more inclined to attempt this via my hack.p6c.org account. Would you be willing to try help me out if I run into problems? I'm as thick as two planks in some ways but, hopefully, not entirely useless...

[AlexDaniel]

/o\ This has got to be a remnant of folks' misinterpretation of what I was suggesting in the first place, right?

I didn't say that we have to do anything, I said we can think :) Thinking is good. After all, there's always something we can do better.

attempt this via my hack.p6c.org account

I may be a plank too. Why not just change this line?

[raiph]

I didn't say that we have to do anything, I said we can think :) Thinking is good.

Nah. That's what led me to open this issue rather than just do a PR in the first place. :)

I could of course have done a PR in the time it took me to write any of the comments in this thread but...

I may be a plank too. Why not just change this line?

Because I may be less intelligent than a plank? :)

When I wrote my first comment about this in early 2015 I thought the whole point was to change just that line of output even though I didn't explicitly say so. By the time I opened this issue 2 years later I had looked at the code and had seen that it was just a single line in the generating code too. But [Coke] wrote "it's a lot of work for little payoff". That strongly suggested to me that I might be missing something. I replied "I had thought this was a one line change" but [Coke] didn't reply and no one else confirmed it was indeed as simple as I thought.

(This combines with the fact that I've made what I thought was a trivial change in the past that turned out to be a quite unwelcome irreversible change. I removed what I considered to be extraneous whitespace but it turned out that my change ruined the utility of the blame feature for the file I changed, and reverting my change would just make things worse.)

And you added an LHF tag rather than just doing the change yourself. I couldn't tell if that's because it was a perfect ultra trivial LHF, a change that would take just a few minutes at most, and the only reason you didn't do it was to encourage someone like me, or if there was more to it than I was understanding.

I actually have to run right now but will do a PR when I next spend some time P6ing, probably later today.

[AlexDaniel]

I couldn't tell if that's because it was a perfect ultra trivial LHF […]

It is, but I'd also prefer someone passionate about the issue to take care of it. For example, it should probably say “Edit this page” instead of simply stating that it was generated from some file. Well, you probably know better.

[coke]

If someone thinks it's easy and wants to contributes a PR, do it.

Don't wait for me to tell you it's easy. Based on the original request, it sounded like a lot of work to me, so I'm not going to work on it.

If you want to, and you think it's easy, just do it. Put together a PR for someone who does have the build tools to give it a shot.

[zakame]

@raiph do you still intend to work on this? I just checked the link from @AlexDaniel and it does seem to be just a couple simple changes (to get started:)

• Point to the edit URL for pages on GitHub
• Rephrase wording on footer to emphasize editing via the above, or posting issue

I can work on this if you don't mind.

[raiph]

Thanks for asking, please go ahead, and thanks in advance for doing whatever you do.

One thing:

• “If not all files have .pod6 extension, then it should be fixed.”

~~ from an earlier comment in this issue by AlexDaniel.

---

(to get started) ... Rephrase wording on footer

• Fwiw I think it would improve things a lot to also have something near the top of the page. Off the top of my head maybe:

• remove the "Documentation for " string that's prepended to the title of some pages (it seems useless; why was it added?) to make more room ;

• Add a ( ... ) in small text following the title containing some stuff, as follows...

• lang version (could initially be a hardcoded string 6.c) ;

• an i or info icon link to 'about doc` ;

• a pencil icon that links to the edit URL ;

But, of course, feel free to close this issue without addressing this stuff at the top; we can always open another issue for that. Just some food for thought.

[rafaelschipiura]

Closing now. If anyone wants to work in the suggestions, please feel free to create another issue.

[AlexDaniel]

Oops, yes, but if you want to split the ticket into multiple issues please don't close the original ticket until new ones are created. Otherwise things get lost. I don't have time for that right now though.

[rafaelschipiura]

Will do.

[rafaelschipiura]

Done, the issue has been split.