Re: [racket-users] Re: GUI (get-directory)

[Sam Tobin-Hochstadt]

First, one thing I would suggest is that you can create pull requests
for anything right from the GitHub UI, although that doesn't let you
test them. Especially for small documentation changes where there's no
chance you're breaking something, I find that to be very effective and
lightweight.

Second, here's how I would go about making a documentation change to
something in the "main" documentation
  - I go to the relevant directory (such as
racket/pkgs/racket-doc/scribblings/reference).
  - I look at the file name of the HTML page I want to change, such as
https://docs.racket-lang.org/reference/envvars.html
  - Edit envvars.scrbl. Sometimes the file name is less easy to find,
such as https://docs.racket-lang.org/reference/Manipulating_Paths.html
Then I use grep (it's in "paths.scrbl", which would be easy to see
from the larger section).
  - Create pull request.

For most other packages, I'd do the following:
  - `raco pkg update --clone the-pkg`
  - cd the-pkg # and then look around for the documentation
  - Other steps as above.

Sam

On Thu, Dec 5, 2019 at 7:56 PM Matt Jadud  wrote:
>
> It feels like much of the information needed to make some of the sign posts 
> for easy contribution are available either 1) automatically available at time 
> of documentation build, or 2) could be added to the info file.
>
> Would someone in the Racket team be able to recommend or suggest some 
> concrete ways the community might approach work that begins addressing the 
> task of making it easier to contribute to docs?
>
> Or, really, anyone with some insight into the tools. Some pointers would help 
> make it easier to contribute productively.
>
> Cheers,
> Matt
>
> On Thu, Dec 5, 2019, 18:29 wanderley.guimar...@gmail.com 
>  wrote:
>>
>> I think your point is totally valid, and I feel that I already saw such 
>> discussion in the mail list.
>>
>> You can simplify the process by searching a piece of the documentation in 
>> github.  For example, I search for a piece of the docs from rackjure (1) 
>> which is the second result in my search.
>>
>>
>> (1) 
>> https://github.com/search?l==macro+automatically+adds+the+parentheses+language%3ARacket=Code
>>
>>
>> On Thu, Dec 5, 2019 at 12:27 PM David Storrs  wrote:
>>>
>>> For the record, my big concern with the documentation is that it's 
>>> extremely hard to contribute to.  I would be delighted to contribute 
>>> documentation if the process was easy, but it's just not.  For a language 
>>> as amazing as Racket and a documentation set as high-quality as Racket's, 
>>> the difficulty of helping with it is surprising.
>>>
>>> tl;dr :  Using literate programming techniques(*) for documentation is a 
>>> bad idea.  So is having random tiny files scattered around instead of one 
>>> single .scrbl file in a location that maps to the URL of the page.
>>>
>>> (*) (i.e., having random tiny files with documentation on one particular 
>>> thing and then automating the process of assembling them)
>>>
>>>
>>> My understanding is that the sequence goes like this:
>>>
>>> 1) Notice a thing you would like to change (a typo fix, add an example, etc)
>>> 1a) Ask on the mailing list how to contribute changes since the Guide / 
>>> Reference / package does not have clear directions built in
>>> 2) Go to Github
>>> 3) Find which racket-related repository is the one that matters for this 
>>> documentation.  The Racket project itself has half a dozen repositories and 
>>> it's not obvious (to me, at least) which one is which.  Things on the 
>>> package server will have a direct link, which helps a lot.
>>> 4) git fork the appropriate repository, git clone it to your local machine
>>> 5) grep -r through the clone to find the document that you want to modify.  
>>> It will not be in a location apparent from the URL of the page you were 
>>> looking at, nor will it be named what that page was named, nor will it 
>>> contain all of the content from that page.  Also, it will be in Scribble, 
>>> which is a DSL that requires non-trivial effort to learn and is non-trivial 
>>> to read.  Still, it produces amazing output so that's probably worth it.  
>>> It's intimidating when you're just getting started, though.
>>> 6a) make your change
>>> 6b) google for how to rebuild scribble documentation
>>> 6c) rebuild (by default this will rebuild all documentation), verify you 
>>> made the change correctly
>>> 7) git commit, git push
>>> 8) go back to github and submit a pull request
>>> 9) (when (eq? (sync pr-msg-ch) 'Accepted) (exit))
>>> 10) make requested changes
>>> 11) git commit, git push, goto 9
>>>
>>> Compare that to what it looks like in, e.g., Perl
>>>
>>> 1) Notice a thing you would like to change (a typo fix, add an example, etc)
>>> 2) got to CPAN and search for the package / tutorial / etc.  clicking on 
>>> the name of the package gets you a listing of all files in the package (cf 
>>> https://metacpan.org/release/ETHER/Moose-2.2012)
>>> 3) click on the 'Package::Name::Contributing' file 

Re: [racket-users] Re: GUI (get-directory)

[Matt Jadud]

It feels like much of the information needed to make some of the sign posts
for easy contribution are available either 1) automatically available at
time of documentation build, or 2) could be added to the info file.

Would someone in the Racket team be able to recommend or suggest some
concrete ways the community might approach work that begins addressing the
task of making it easier to contribute to docs?

Or, really, anyone with some insight into the tools. Some pointers would
help make it easier to contribute productively.

Cheers,
Matt

On Thu, Dec 5, 2019, 18:29 wanderley.guimar...@gmail.com <
wanderley.guimar...@gmail.com> wrote:

> I think your point is totally valid, and I feel that I already saw such
> discussion in the mail list.
>
> You can simplify the process by searching a piece of the documentation in
> github.  For example, I search for a piece of the docs from rackjure (1)
> which is the second result in my search.
>
>
> (1)
> https://github.com/search?l==macro+automatically+adds+the+parentheses+language%3ARacket=Code
>
>
> On Thu, Dec 5, 2019 at 12:27 PM David Storrs 
> wrote:
>
>> For the record, my big concern with the documentation is that it's
>> extremely hard to contribute to.  I would be delighted to contribute
>> documentation if the process was easy, but it's just not.  For a language
>> as amazing as Racket and a documentation set as high-quality as Racket's,
>> the difficulty of helping with it is surprising.
>>
>> tl;dr :  Using literate programming techniques(*) for documentation is a
>> bad idea.  So is having random tiny files scattered around instead of one
>> single .scrbl file in a location that maps to the URL of the page.
>>
>> (*) (i.e., having random tiny files with documentation on one particular
>> thing and then automating the process of assembling them)
>>
>>
>> My understanding is that the sequence goes like this:
>>
>> 1) Notice a thing you would like to change (a typo fix, add an example,
>> etc)
>> 1a) Ask on the mailing list how to contribute changes since the Guide /
>> Reference / package does not have clear directions built in
>> 2) Go to Github
>> 3) Find which racket-related repository is the one that matters for this
>> documentation.  The Racket project itself has half a dozen repositories and
>> it's not obvious (to me, at least) which one is which.  Things on the
>> package server will have a direct link, which helps a lot.
>> 4) git fork the appropriate repository, git clone it to your local machine
>> 5) grep -r through the clone to find the document that you want to
>> modify.  It will not be in a location apparent from the URL of the page you
>> were looking at, nor will it be named what that page was named, nor will it
>> contain all of the content from that page.  Also, it will be in Scribble,
>> which is a DSL that requires non-trivial effort to learn and is non-trivial
>> to read.  Still, it produces amazing output so that's probably worth it.
>> It's intimidating when you're just getting started, though.
>> 6a) make your change
>> 6b) google for how to rebuild scribble documentation
>> 6c) rebuild (by default this will rebuild all documentation), verify you
>> made the change correctly
>> 7) git commit, git push
>> 8) go back to github and submit a pull request
>> 9) (when (eq? (sync pr-msg-ch) 'Accepted) (exit))
>> 10) make requested changes
>> 11) git commit, git push, goto 9
>>
>> Compare that to what it looks like in, e.g., Perl
>>
>> 1) Notice a thing you would like to change (a typo fix, add an example,
>> etc)
>> 2) got to CPAN and search for the package / tutorial / etc.  clicking on
>> the name of the package gets you a listing of all files in the package (cf
>> https://metacpan.org/release/ETHER/Moose-2.2012)
>> 3) click on the 'Package::Name::Contributing' file and do what it says.
>> This will probably be similar to the Racket workflow except that:
>>
>> a) The complete details are spelled out.
>> b) There is a link directly to the repository
>> c) The location of the file you need to edit is obvious from the URL of
>> the documentation page that you're changing
>> d) The file contains the complete text of the page so it's easier to find
>> and easier to verify that your edits were correct
>> e) The file is in POD, which is so simple that you can generally learn
>> what you need just from glancing at the file, and it's easier to read than
>> Scribble.  It's simple enough that you generally don't need to rebuild it
>> to HTML, but if you choose to then you can easily rebuild just that page.
>>
>> Example of a Contributing file:
>> https://metacpan.org/pod/release/ETHER/Moose-2.2012/lib/Moose/Manual/Contributing.pod
>>
>>   (NB:  All major Perl packages have a Contributing file and the 'create
>> a package' tool for generating Perl modules creates a stub version for you
>> so it's hard to forget.  If the author somehow *does* forget and the
>> package doesn't have its own Contributing file then CPAN will show you a
>> default 

Re: [racket-users] Re: GUI (get-directory)

[wanderley.guimar...@gmail.com]

I think your point is totally valid, and I feel that I already saw such
discussion in the mail list.

You can simplify the process by searching a piece of the documentation in
github.  For example, I search for a piece of the docs from rackjure (1)
which is the second result in my search.


(1)
https://github.com/search?l==macro+automatically+adds+the+parentheses+language%3ARacket=Code


On Thu, Dec 5, 2019 at 12:27 PM David Storrs  wrote:

> For the record, my big concern with the documentation is that it's
> extremely hard to contribute to.  I would be delighted to contribute
> documentation if the process was easy, but it's just not.  For a language
> as amazing as Racket and a documentation set as high-quality as Racket's,
> the difficulty of helping with it is surprising.
>
> tl;dr :  Using literate programming techniques(*) for documentation is a
> bad idea.  So is having random tiny files scattered around instead of one
> single .scrbl file in a location that maps to the URL of the page.
>
> (*) (i.e., having random tiny files with documentation on one particular
> thing and then automating the process of assembling them)
>
>
> My understanding is that the sequence goes like this:
>
> 1) Notice a thing you would like to change (a typo fix, add an example,
> etc)
> 1a) Ask on the mailing list how to contribute changes since the Guide /
> Reference / package does not have clear directions built in
> 2) Go to Github
> 3) Find which racket-related repository is the one that matters for this
> documentation.  The Racket project itself has half a dozen repositories and
> it's not obvious (to me, at least) which one is which.  Things on the
> package server will have a direct link, which helps a lot.
> 4) git fork the appropriate repository, git clone it to your local machine
> 5) grep -r through the clone to find the document that you want to
> modify.  It will not be in a location apparent from the URL of the page you
> were looking at, nor will it be named what that page was named, nor will it
> contain all of the content from that page.  Also, it will be in Scribble,
> which is a DSL that requires non-trivial effort to learn and is non-trivial
> to read.  Still, it produces amazing output so that's probably worth it.
> It's intimidating when you're just getting started, though.
> 6a) make your change
> 6b) google for how to rebuild scribble documentation
> 6c) rebuild (by default this will rebuild all documentation), verify you
> made the change correctly
> 7) git commit, git push
> 8) go back to github and submit a pull request
> 9) (when (eq? (sync pr-msg-ch) 'Accepted) (exit))
> 10) make requested changes
> 11) git commit, git push, goto 9
>
> Compare that to what it looks like in, e.g., Perl
>
> 1) Notice a thing you would like to change (a typo fix, add an example,
> etc)
> 2) got to CPAN and search for the package / tutorial / etc.  clicking on
> the name of the package gets you a listing of all files in the package (cf
> https://metacpan.org/release/ETHER/Moose-2.2012)
> 3) click on the 'Package::Name::Contributing' file and do what it says.
> This will probably be similar to the Racket workflow except that:
>
> a) The complete details are spelled out.
> b) There is a link directly to the repository
> c) The location of the file you need to edit is obvious from the URL of
> the documentation page that you're changing
> d) The file contains the complete text of the page so it's easier to find
> and easier to verify that your edits were correct
> e) The file is in POD, which is so simple that you can generally learn
> what you need just from glancing at the file, and it's easier to read than
> Scribble.  It's simple enough that you generally don't need to rebuild it
> to HTML, but if you choose to then you can easily rebuild just that page.
>
> Example of a Contributing file:
> https://metacpan.org/pod/release/ETHER/Moose-2.2012/lib/Moose/Manual/Contributing.pod
>
>   (NB:  All major Perl packages have a Contributing file and the 'create a
> package' tool for generating Perl modules creates a stub version for you so
> it's hard to forget.  If the author somehow *does* forget and the package
> doesn't have its own Contributing file then CPAN will show you a default
> version that contains all critical information.  Also, it's easy to find
> the Contributing file:  Go to the package listing that's available directly
> on CPAN and Ctrl+F for "Contributing")
>
>
>
> On Tue, Dec 3, 2019 at 5:26 PM James Platt  wrote:
>
>>
>> On Nov 25, 2019, at 1:29 PM, Stephen De Gabrielle wrote:
>>
>> > Many packages contain an /examples folder, and adding examples is an
>> easy way to contribute.
>>
>> I did not know that.  So, I guess the strategy is to find the git
>> repository for the package and look there?  In any case, I haven't been
>> finding these examples with a general web search.
>>
>> >
>> > There is also https://github.com/racket/racket/wiki/Artifacts
>> >
>> >> This page captures useful code 

Re: [racket-users] Re: GUI (get-directory)

[David Storrs]

For the record, my big concern with the documentation is that it's
extremely hard to contribute to.  I would be delighted to contribute
documentation if the process was easy, but it's just not.  For a language
as amazing as Racket and a documentation set as high-quality as Racket's,
the difficulty of helping with it is surprising.

tl;dr :  Using literate programming techniques(*) for documentation is a
bad idea.  So is having random tiny files scattered around instead of one
single .scrbl file in a location that maps to the URL of the page.

(*) (i.e., having random tiny files with documentation on one particular
thing and then automating the process of assembling them)


My understanding is that the sequence goes like this:

1) Notice a thing you would like to change (a typo fix, add an example, etc)
1a) Ask on the mailing list how to contribute changes since the Guide /
Reference / package does not have clear directions built in
2) Go to Github
3) Find which racket-related repository is the one that matters for this
documentation.  The Racket project itself has half a dozen repositories and
it's not obvious (to me, at least) which one is which.  Things on the
package server will have a direct link, which helps a lot.
4) git fork the appropriate repository, git clone it to your local machine
5) grep -r through the clone to find the document that you want to modify.
It will not be in a location apparent from the URL of the page you were
looking at, nor will it be named what that page was named, nor will it
contain all of the content from that page.  Also, it will be in Scribble,
which is a DSL that requires non-trivial effort to learn and is non-trivial
to read.  Still, it produces amazing output so that's probably worth it.
It's intimidating when you're just getting started, though.
6a) make your change
6b) google for how to rebuild scribble documentation
6c) rebuild (by default this will rebuild all documentation), verify you
made the change correctly
7) git commit, git push
8) go back to github and submit a pull request
9) (when (eq? (sync pr-msg-ch) 'Accepted) (exit))
10) make requested changes
11) git commit, git push, goto 9

Compare that to what it looks like in, e.g., Perl

1) Notice a thing you would like to change (a typo fix, add an example, etc)
2) got to CPAN and search for the package / tutorial / etc.  clicking on
the name of the package gets you a listing of all files in the package (cf
https://metacpan.org/release/ETHER/Moose-2.2012)
3) click on the 'Package::Name::Contributing' file and do what it says.
This will probably be similar to the Racket workflow except that:

a) The complete details are spelled out.
b) There is a link directly to the repository
c) The location of the file you need to edit is obvious from the URL of the
documentation page that you're changing
d) The file contains the complete text of the page so it's easier to find
and easier to verify that your edits were correct
e) The file is in POD, which is so simple that you can generally learn what
you need just from glancing at the file, and it's easier to read than
Scribble.  It's simple enough that you generally don't need to rebuild it
to HTML, but if you choose to then you can easily rebuild just that page.

Example of a Contributing file:
https://metacpan.org/pod/release/ETHER/Moose-2.2012/lib/Moose/Manual/Contributing.pod

  (NB:  All major Perl packages have a Contributing file and the 'create a
package' tool for generating Perl modules creates a stub version for you so
it's hard to forget.  If the author somehow *does* forget and the package
doesn't have its own Contributing file then CPAN will show you a default
version that contains all critical information.  Also, it's easy to find
the Contributing file:  Go to the package listing that's available directly
on CPAN and Ctrl+F for "Contributing")



On Tue, Dec 3, 2019 at 5:26 PM James Platt  wrote:

>
> On Nov 25, 2019, at 1:29 PM, Stephen De Gabrielle wrote:
>
> > Many packages contain an /examples folder, and adding examples is an
> easy way to contribute.
>
> I did not know that.  So, I guess the strategy is to find the git
> repository for the package and look there?  In any case, I haven't been
> finding these examples with a general web search.
>
> >
> > There is also https://github.com/racket/racket/wiki/Artifacts
> >
> >> This page captures useful code snippets that are too small to be a
> package.
> >>
> >> Please contribute your own!
> >
> > Though these might be better places in documentation, or in /examples
>
> That artifacts wiki a good thing to know about.  Most of these are a
> little more complex than I am thinking are good for documentation but I may
> well contribute some small but useful code.  I sometimes create my own
> examples as I go because I often look back through my own code to refresh
> my memory on how to do something.
>
> --
> You received this message because you are subscribed to the Google Groups
> "Racket Users" group.
> To 

Re: [racket-users] Re: GUI (get-directory)

[James Platt]

On Nov 25, 2019, at 1:29 PM, Stephen De Gabrielle wrote:

> Many packages contain an /examples folder, and adding examples is an easy way 
> to contribute.

I did not know that.  So, I guess the strategy is to find the git repository 
for the package and look there?  In any case, I haven't been finding these 
examples with a general web search.

> 
> There is also https://github.com/racket/racket/wiki/Artifacts
> 
>> This page captures useful code snippets that are too small to be a package.
>> 
>> Please contribute your own!
> 
> Though these might be better places in documentation, or in /examples

That artifacts wiki a good thing to know about.  Most of these are a little 
more complex than I am thinking are good for documentation but I may well 
contribute some small but useful code.  I sometimes create my own examples as I 
go because I often look back through my own code to refresh my memory on how to 
do something.  

-- 
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.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/racket-users/D5A56D93-963F-412D-9CA6-7DE3A17F6148%40biomantica.com.

Re: [racket-users] Re: GUI (get-directory)

[Stephen De Gabrielle]

Many packages contain an /examples folder, and adding examples is an easy way 
to contribute.

There is also https://github.com/racket/racket/wiki/Artifacts

> This page captures useful code snippets that are too small to be a package.
> 
> Please contribute your own!

Though these might be better places in documentation, or in /examples

S.

-- 
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.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/racket-users/b02f0a32-8790-442f-b2a6-21086e8b3c1e%40googlegroups.com.

Re: [racket-users] Re: GUI (get-directory)

[Laurent]

There may be some examples on Rosetta code, or at least Racket snippets
could be added:
https://rosettacode.org/wiki/Category:GUI

On Sat, Nov 23, 2019, 00:23 Martin DeMello  wrote:

> One helpful thing to do is expand the GUI section of awesome-racket
> https://github.com/avelino/awesome-racket
>
> I just sent them a PR for GUI-helpers.
>
> martin
>
> On Thu, Nov 21, 2019 at 9:21 AM James Platt  wrote:
>
>>
>> On Nov 20, 2019, at 3:31 AM, Jack Firth wrote:
>>
>> > Would it have helped if the get-directory documentation had included
>> examples? Many parts of Racket's documentation are lacking in example code,
>> especially the less-commonly-encountered parts.
>>
>> Indeed, I have previously mentioned the lack of examples as a general
>> problem.  However, many potential examples may already be written in the
>> form of test code.  There is a way to add a sandbox to Scribble which
>> allows you to write test code and documentation at the same time.  It would
>> be great if this could be made easier to set up and then promoted for wider
>> use.  One place where it has been used is the struct++ package.
>>
>> See:
>> https://docs.racket-lang.org/struct-plus-plus/index.html
>>
>> https://github.com/dstorrs/struct-plus-plus/blob/master/scribblings/struct-plus-plus.scrbl
>>
>> Also, as David Storrs has mentioned, it would be good if we can find a
>> way to make it easier for more people to contribute to the documentation.
>> See, for example, the thread "Wanted: Easier way to contribute docs" on
>> this forum from June of 2017.
>>
>> If we can direct more of the energy of this community into, not just
>> improving the documentation, but the way we do documentation, it would be a
>> major improvement.  Requiring lots of parentheses doesn't bother me.  Lack
>> of infix notation doesn't bother me.  Lack of documentation does.
>>
>> James
>>
>> --
>> 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.
>> To view this discussion on the web visit
>> https://groups.google.com/d/msgid/racket-users/934E0BEE-5840-4596-975F-410C3770DBA6%40biomantica.com
>> .
>>
> --
> 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.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/racket-users/CAFrFfuEd7b3Y_aQ5rHq32tDE_iR06nrJp2J1RRaDsWaYKBhpkg%40mail.gmail.com
> 
> .
>

-- 
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.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/racket-users/CABNTSaH0dp2OeNyi9krhzCXospGGRrY5qgY_zZCbqKND8VGg6g%40mail.gmail.com.

Re: [racket-users] Re: GUI (get-directory)

[Martin DeMello]

One helpful thing to do is expand the GUI section of awesome-racket
https://github.com/avelino/awesome-racket

I just sent them a PR for GUI-helpers.

martin

On Thu, Nov 21, 2019 at 9:21 AM James Platt  wrote:

>
> On Nov 20, 2019, at 3:31 AM, Jack Firth wrote:
>
> > Would it have helped if the get-directory documentation had included
> examples? Many parts of Racket's documentation are lacking in example code,
> especially the less-commonly-encountered parts.
>
> Indeed, I have previously mentioned the lack of examples as a general
> problem.  However, many potential examples may already be written in the
> form of test code.  There is a way to add a sandbox to Scribble which
> allows you to write test code and documentation at the same time.  It would
> be great if this could be made easier to set up and then promoted for wider
> use.  One place where it has been used is the struct++ package.
>
> See:
> https://docs.racket-lang.org/struct-plus-plus/index.html
>
> https://github.com/dstorrs/struct-plus-plus/blob/master/scribblings/struct-plus-plus.scrbl
>
> Also, as David Storrs has mentioned, it would be good if we can find a way
> to make it easier for more people to contribute to the documentation.  See,
> for example, the thread "Wanted: Easier way to contribute docs" on this
> forum from June of 2017.
>
> If we can direct more of the energy of this community into, not just
> improving the documentation, but the way we do documentation, it would be a
> major improvement.  Requiring lots of parentheses doesn't bother me.  Lack
> of infix notation doesn't bother me.  Lack of documentation does.
>
> James
>
> --
> 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.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/racket-users/934E0BEE-5840-4596-975F-410C3770DBA6%40biomantica.com
> .
>

-- 
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.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/racket-users/CAFrFfuEd7b3Y_aQ5rHq32tDE_iR06nrJp2J1RRaDsWaYKBhpkg%40mail.gmail.com.

Re: [racket-users] Re: GUI (get-directory)

[James Platt]

On Nov 20, 2019, at 3:31 AM, Jack Firth wrote:

> Would it have helped if the get-directory documentation had included 
> examples? Many parts of Racket's documentation are lacking in example code, 
> especially the less-commonly-encountered parts.

Indeed, I have previously mentioned the lack of examples as a general problem.  
However, many potential examples may already be written in the form of test 
code.  There is a way to add a sandbox to Scribble which allows you to write 
test code and documentation at the same time.  It would be great if this could 
be made easier to set up and then promoted for wider use.  One place where it 
has been used is the struct++ package.

See:
https://docs.racket-lang.org/struct-plus-plus/index.html
https://github.com/dstorrs/struct-plus-plus/blob/master/scribblings/struct-plus-plus.scrbl

Also, as David Storrs has mentioned, it would be good if we can find a way to 
make it easier for more people to contribute to the documentation.  See, for 
example, the thread "Wanted: Easier way to contribute docs" on this forum from 
June of 2017.  

If we can direct more of the energy of this community into, not just improving 
the documentation, but the way we do documentation, it would be a major 
improvement.  Requiring lots of parentheses doesn't bother me.  Lack of infix 
notation doesn't bother me.  Lack of documentation does.

James

-- 
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.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/racket-users/934E0BEE-5840-4596-975F-410C3770DBA6%40biomantica.com.

Re: [racket-users] Re: GUI (get-directory)

[pow bam]

I can't speak for others but for me I feel it would have helped a great 
deal in enabling me to quickly figure out how it was supposed to actually 
be used. What was tripping me up the most I guess was 1) it appeared to me 
I needed to use the brackets like shown in the documentation, and 2) that 
it was wanting some keyword (like "message") there.

Except for that I rather do feel so far that it is a great language for 
beginners to learn and it even appears that it is in part aimed at 
beginners in spite of the fact it is a language that professional scientist 
types developed. It's a bit of a shame there are few serious, well done 
video (YouTube) tutorials covering vital aspects like how to get a simple 
GUI for an app put together - which for the most part is surprisingly 
simple to do compared to other languages I've experimented with up until 
this point. I had been fiddling with Python prior - which, as you'd expect, 
has a massive amount of community material out there in the void - but I 
wandered onto Racket and, except for the documentation snafu I experienced, 
I find it to be an incredibly appealing language.

On Wednesday, November 20, 2019 at 2:31:21 AM UTC-6, Jack Firth wrote:
>
> Would it have helped if the get-directory documentation had included 
> examples? Many parts of Racket's documentation are lacking in example code, 
> especially the less-commonly-encountered parts.
>

-- 
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.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/racket-users/700cdde3-38a4-4f3e-b1f8-ba2dcb583bb4%40googlegroups.com.

Re: [racket-users] Re: GUI (get-directory)

[Jack Firth]

Would it have helped if the get-directory documentation had included 
examples? Many parts of Racket's documentation are lacking in example code, 
especially the less-commonly-encountered parts.

On Tuesday, November 19, 2019 at 10:52:14 PM UTC-8, pow bam wrote:
>
> Indeed I would have likely never even known that section existed - and 
> looking at it now I see that it is very dense reading material. I turns my 
> mind to mush trying to interpret what's being said there. I also happen to 
> be, by and large, a self-learning lone wolf type. I am a complete novice to 
> programming but when it came to AutoIt I managed to figure out how to piece 
> together a fairly complicated and large-ish program only using Google, 
> typing in Autoit + whateverineededtoknowabout and it invariably led me to 
> not only just the documentation but a community forum FULL of questions and 
> answers from years of community involvement. Sadly, Racket has no such 
> structure in place except this very secluded, small Google group and 
> smattering of tuts about the web - hardly any of which actually focus in 
> any depth upon GUI app creation to any real extent, seemingly more 
> concerned with various game making and animation activities.
>
> As an example take a look at what happens if I type this into Google for 
> an AutoIt function:
> https://www.google.com/search?q=autoit+get+window+size
>
> I wind up with a list of forum entries that I can read for clues on what 
> to do OR I can read the documentation along with all that and if you look 
> at the documentation..
> https://www.autoitscript.com/autoit3/docs/functions/WinGetClientSize.htm
> ..it not only gives me a more traditional breakdown of the function it 
> then goes on to show me it in real world use/action. That's a powerful 
> thing to getting new people and beginners in the door and using your 
> language. I would actually be much happier with a true official forum. 
> Nothing against Google, I guess, but it feels so spartan and limited 
> compared to what it could be.
>

-- 
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.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/racket-users/62cc63a4-196c-4294-b147-6c1ec3023732%40googlegroups.com.

Re: [racket-users] Re: GUI (get-directory)

[pow bam]

Indeed I would have likely never even known that section existed - and 
looking at it now I see that it is very dense reading material. I turns my 
mind to mush trying to interpret what's being said there. I also happen to 
be, by and large, a self-learning lone wolf type. I am a complete novice to 
programming but when it came to AutoIt I managed to figure out how to piece 
together a fairly complicated and large-ish program only using Google, 
typing in Autoit + whateverineededtoknowabout and it invariably led me to 
not only just the documentation but a community forum FULL of questions and 
answers from years of community involvement. Sadly, Racket has no such 
structure in place except this very secluded, small Google group and 
smattering of tuts about the web - hardly any of which actually focus in 
any depth upon GUI app creation to any real extent, seemingly more 
concerned with various game making and animation activities.

As an example take a look at what happens if I type this into Google for an 
AutoIt function:
https://www.google.com/search?q=autoit+get+window+size

I wind up with a list of forum entries that I can read for clues on what to 
do OR I can read the documentation along with all that and if you look at 
the documentation..
https://www.autoitscript.com/autoit3/docs/functions/WinGetClientSize.htm
..it not only gives me a more traditional breakdown of the function it then 
goes on to show me it in real world use/action. That's a powerful thing to 
getting new people and beginners in the door and using your language. I 
would actually be much happier with a true official forum. Nothing against 
Google, I guess, but it feels so spartan and limited compared to what it 
could be.

-- 
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.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/racket-users/db9ee588-3457-41ef-b102-b85cdfeafa12%40googlegroups.com.

Re: [racket-users] Re: GUI (get-directory)

[George Neuner]

On 11/19/2019 2:04 PM, pow bam wrote:
Ah thank you very much Hadi.. that indeed worked out nicely and now 
makes alot more sense to me. The documentation structure can be a bit 
confusing/misleading on points like this and I rather wish that they 
would display "real world" usage examples more in-depth in the docs 
for clarity. Again thank you.


You might want to have a look at this page that describes the 
conventions used in the manul:
    "Notation for Documentation" - 
https://docs.racket-lang.org/reference/notation.html



Probably there should be a link to this on the main documentation page - 
or an intro section on "how to read the manual" right up front.   We 
can't reasonably expect novices to know the notation conventions.


George

--
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.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/racket-users/84161a5d-166b-c369-2d0a-7a671e1dfe18%40comcast.net.

[racket-users] Re: GUI (get-directory)

[pow bam]

Ah thank you very much Hadi.. that indeed worked out nicely and now makes 
alot more sense to me. The documentation structure can be a bit 
confusing/misleading on points like this and I rather wish that they would 
display "real world" usage examples more in-depth in the docs for clarity. 
Again thank you.

-- 
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.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/racket-users/e4273e34-b309-4387-9ee6-db2135b7435c%40googlegroups.com.