Re: [racket-users] Wanted: Easier way to contribute docs

[Ben Greenman]

>
> This is a nice idea, though possibly complicated to implement (AFAICT it
> would require annotating the HTML of a given part of the documentation with
> a reference to the source code that originally generated it, and in a way
> that can be generalized to every Racket project, not just the ones in the
> main `racket` repo.)


I think the way to generalize is to add an `info.rkt` field for the
project's source. Could be GitHub, could be another website.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] Wanted: Easier way to contribute docs

[Jens Axel Søgaard]

FWIW  For a casual contributor wanting to report a single spelling error,
add a single sentence or similar - the Github pencil seems to be an easy
way of making a pull request.

https://github.com/racket/racket/blob/master/pkgs/racket-doc/scribblings/guide/begin.scrbl

See the pencil at the right  (to the left of the trashcan).

/Jens Axel


2017-06-13 20:59 GMT+02:00 Matthew Butterick :

>
> On Jun 13, 2017, at 6:34 AM, David Storrs  wrote:
>
> There needs to be an easy and obvious way to edit the pages at
> docs.racket-lang.org or an easy and obvious way to go from the page to
> the relevant part of the GitHub repository
>
>
> This is a nice idea, though possibly complicated to implement (AFAICT it
> would require annotating the HTML of a given part of the documentation with
> a reference to the source code that originally generated it, and in a way
> that can be generalized to every Racket project, not just the ones in the
> main `racket` repo.)
>
> But documentation is used by everyone, not just developers. It would be
> even nicer / more inclusive to have a way to collect feedback on the docs
> that doesn't rely on, say, Scribble sources and pull requests.
>
> --
> You received this message because you are subscribed to the Google Groups
> "Racket Users" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to racket-users+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>



-- 
-- 
Jens Axel Søgaard

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] Wanted: Easier way to contribute docs

[Matthew Butterick]

> On Jun 13, 2017, at 6:34 AM, David Storrs  wrote:
> 
> There needs to be an easy and obvious way to edit the pages at 
> docs.racket-lang.org  or an easy and obvious 
> way to go from the page to the relevant part of the GitHub repository

This is a nice idea, though possibly complicated to implement (AFAICT it would 
require annotating the HTML of a given part of the documentation with a 
reference to the source code that originally generated it, and in a way that 
can be generalized to every Racket project, not just the ones in the main 
`racket` repo.) 

But documentation is used by everyone, not just developers. It would be even 
nicer / more inclusive to have a way to collect feedback on the docs that 
doesn't rely on, say, Scribble sources and pull requests.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] Wanted: Easier way to contribute docs

[Leif Andersen]

> A lot of sites show a hyperlink icon (two chain links typically) when you 
> mouse over a section title. We could do that along with an edit icon instead 
> of requiring users click the section header. That would be more discoverable 
> and more in line with what other sites like Github do IMO.

I'm not opposed to that, but I don't really have the cycles to figure
out how to do it. ;)

~Leif Andersen


On Tue, Jun 13, 2017 at 1:42 PM, Jack Firth  wrote:
>> It might also be a good idea to have the documentation generator put a 
>> standard sentence at the top of each page: "Click on a section header to 
>> find out how to link to it or edit it."
>
> A lot of sites show a hyperlink icon (two chain links typically) when you 
> mouse over a section title. We could do that along with an edit icon instead 
> of requiring users click the section header. That would be more discoverable 
> and more in line with what other sites like Github do IMO.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] Wanted: Easier way to contribute docs

[Jack Firth]

> It might also be a good idea to have the documentation generator put a 
> standard sentence at the top of each page: "Click on a section header to find 
> out how to link to it or edit it."

A lot of sites show a hyperlink icon (two chain links typically) when you mouse 
over a section title. We could do that along with an edit icon instead of 
requiring users click the section header. That would be more discoverable and 
more in line with what other sites like Github do IMO.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] Wanted: Easier way to contribute docs

[David Storrs]

Yep, that would be fine.  It might also be a good idea to have the
documentation generator put a standard sentence at the top of each page:
"Click on a section header to find out how to link to it or edit it."

On Tue, Jun 13, 2017 at 9:38 AM, Leif Andersen 
wrote:

> When you click on a section title, something like this pops up:
>
> Link to this section with
>  @secref["sync" #:doc '(lib "scribblings/reference/reference.scrbl")]
>
> Would it be sufficient to also have:
>
> Edit this section at:
>   
>
> I know its not ideal, but this seems like the easiest possible way to
> go about it.
>
> ~Leif Andersen
>
>
> On Tue, Jun 13, 2017 at 9:34 AM, David Storrs 
> wrote:
> > I've mentioned this on list before but wanted to bump it:
> >
> > It is too difficult to contribute to the Racket docs.  There needs to be
> an
> > easy and obvious way to edit the pages at docs.racket-lang.org or an
> easy
> > and obvious way to go from the page to the relevant part of the GitHub
> > repository.
> >
> > I have this experience frequently:
> >
> > 1) Read through docs, find something that seems incomplete or difficult
> to
> > comprehend, want to contribute a refinement.
> >
> > 2) Realize I don't remember how to do that.  The answer was provided on
> the
> > list when I asked about it months (a year?) ago, but it involved
> something
> > like "click section title to get scribble reference, load github page for
> > Racket, click correct github racket repository, navigate to part of repos
> > that corresponds to the scribble reference, click the pencil icon, write
> > contribution, do...something? in order to send pull request."
> >
> > 3) Debate for a moment if I want to (a) dig through the list to find the
> > answer and then execute it or (b) continue making progress on my task for
> > work.
> >
> > 4) Continue making progress on my task for work.
> >
> >
> > The immediate answer is that I should write down the 'how to contribute'
> > answer in an easily-referencable form on my local machine or else keep a
> > bookmark to the answer.
> >
> > The better answer would be that there is a link at the top of each
> section
> > (each function?) that will take me to the corresponding file in the
> GitHub
> > repository.
> >
> > The best answer is that I would be able to edit the docs inline and the
> > changes would then be packaged up as a pull request and sent to git.
> > Creating this version is almost certainly too much work for anything run
> by
> > volunteers.
> >
> >
> > For the record, the thing that brought this to mind is that I found
> myself
> > wanting 'slice', realized that it wasn't in the Lists docs, googled,
> found
> > that it might be under Sequences [it isn't for Racket but is for other
> > Lisps], wanted to add a link on the Lists page saying "incidentally,
> lists
> > are sequences so you should also check out those for additional
> > functionality."
> >
> >
> >
> > --
> > You received this message because you are subscribed to the Google Groups
> > "Racket Users" group.
> > To unsubscribe from this group and stop receiving emails from it, send an
> > email to racket-users+unsubscr...@googlegroups.com.
> > For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Re: [racket-users] Wanted: Easier way to contribute docs

[Leif Andersen]

When you click on a section title, something like this pops up:

Link to this section with
 @secref["sync" #:doc '(lib "scribblings/reference/reference.scrbl")]

Would it be sufficient to also have:

Edit this section at:
  

I know its not ideal, but this seems like the easiest possible way to
go about it.

~Leif Andersen


On Tue, Jun 13, 2017 at 9:34 AM, David Storrs  wrote:
> I've mentioned this on list before but wanted to bump it:
>
> It is too difficult to contribute to the Racket docs.  There needs to be an
> easy and obvious way to edit the pages at docs.racket-lang.org or an easy
> and obvious way to go from the page to the relevant part of the GitHub
> repository.
>
> I have this experience frequently:
>
> 1) Read through docs, find something that seems incomplete or difficult to
> comprehend, want to contribute a refinement.
>
> 2) Realize I don't remember how to do that.  The answer was provided on the
> list when I asked about it months (a year?) ago, but it involved something
> like "click section title to get scribble reference, load github page for
> Racket, click correct github racket repository, navigate to part of repos
> that corresponds to the scribble reference, click the pencil icon, write
> contribution, do...something? in order to send pull request."
>
> 3) Debate for a moment if I want to (a) dig through the list to find the
> answer and then execute it or (b) continue making progress on my task for
> work.
>
> 4) Continue making progress on my task for work.
>
>
> The immediate answer is that I should write down the 'how to contribute'
> answer in an easily-referencable form on my local machine or else keep a
> bookmark to the answer.
>
> The better answer would be that there is a link at the top of each section
> (each function?) that will take me to the corresponding file in the GitHub
> repository.
>
> The best answer is that I would be able to edit the docs inline and the
> changes would then be packaged up as a pull request and sent to git.
> Creating this version is almost certainly too much work for anything run by
> volunteers.
>
>
> For the record, the thing that brought this to mind is that I found myself
> wanting 'slice', realized that it wasn't in the Lists docs, googled, found
> that it might be under Sequences [it isn't for Racket but is for other
> Lisps], wanted to add a link on the Lists page saying "incidentally, lists
> are sequences so you should also check out those for additional
> functionality."
>
>
>
> --
> You received this message because you are subscribed to the Google Groups
> "Racket Users" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to racket-users+unsubscr...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[racket-users] Wanted: Easier way to contribute docs

[David Storrs]

I've mentioned this on list before but wanted to bump it:

It is too difficult to contribute to the Racket docs.  There needs to be an
easy and obvious way to edit the pages at docs.racket-lang.org or an easy
and obvious way to go from the page to the relevant part of the GitHub
repository.

I have this experience frequently:

1) Read through docs, find something that seems incomplete or difficult to
comprehend, want to contribute a refinement.

2) Realize I don't remember how to do that.  The answer was provided on the
list when I asked about it months (a year?) ago, but it involved something
like "click section title to get scribble reference, load github page for
Racket, click correct github racket repository, navigate to part of repos
that corresponds to the scribble reference, click the pencil icon, write
contribution, do...something? in order to send pull request."

3) Debate for a moment if I want to (a) dig through the list to find the
answer and then execute it or (b) continue making progress on my task for
work.

4) Continue making progress on my task for work.


The immediate answer is that I should write down the 'how to contribute'
answer in an easily-referencable form on my local machine or else keep a
bookmark to the answer.

The better answer would be that there is a link at the top of each section
(each function?) that will take me to the corresponding file in the GitHub
repository.

The best answer is that I would be able to edit the docs inline and the
changes would then be packaged up as a pull request and sent to git.
Creating this version is almost certainly too much work for anything run by
volunteers.


For the record, the thing that brought this to mind is that I found myself
wanting 'slice', realized that it wasn't in the Lists docs, googled, found
that it might be under Sequences [it isn't for Racket but is for other
Lisps], wanted to add a link on the Lists page saying "incidentally, lists
are sequences so you should also check out those for additional
functionality."

-- 
You received this message because you are subscribed to the Google Groups 
"Racket Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to racket-users+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.