You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@whimsical.apache.org by Shane Curcuru <as...@shanecurcuru.org> on 2017/05/26 22:34:46 UTC
Making Whimsy tools user-friendly and findable
I plan to implement some UI and documentation changes to most of the
*.cgi in /www, to have simple documentation in every page, as well as
adding some related links to pages. There are a lot of highly useful -
if not required - tools on Whimsy now, and it would be nice to help
users find them more easily.
See this example for what I'm doing:
https://whimsy.apache.org/committers/tools
- "About This Script" would include a short "how-to / what this does"
blurb for almost all single-cgi tools (I'm not working on /roster or
board/ tools which have their own UI yet).
- "More Whimsy" will be a manually curated list of related links for
that page. This will help users find other informational or process
tools that are available.
- Note the smaller navbar/footer, and the required copyright and ASF
links now appear in the Apache dropdown menu.
A second task is making the /committers/tools list be comprehensive of
all the available scripts that Whimsy provides. Since many tools are
access restricted, I plan to put color-coded glyphicon-lock icons next
to each URL so there's a hint for people which things they can use.
Separately, what do people think about adding Google Analytics to some
of the major tools & homepage to see how much traffic Whimsy tools get?
Great Idea / Heck No / OK, Shane, go be crazy if you really want?
--
- Shane
https://www.apache.org/foundation/marks/resources
Re: Making Whimsy tools user-friendly and findable
Posted by Shane Curcuru <as...@shanecurcuru.org>.
sebb wrote on 5/27/17 5:07 AM:
> On 26 May 2017 at 23:34, Shane Curcuru <as...@shanecurcuru.org> wrote:
...snip...
>> A second task is making the /committers/tools list be comprehensive of
>> all the available scripts that Whimsy provides. Since many tools are
>> access restricted, I plan to put color-coded glyphicon-lock icons next
>> to each URL so there's a hint for people which things they can use.
>
> Remember that some colours cannot easily be distinguished by some people.
> Some may even not be able to distinguish colours at all.
> So colour should not be the only visually distint quality.
Ack. Patches that are visually attractive in the output welcome. The
color is not a required item; merely a hint at which auth you get if you
click the link. An eye icon is used for public links with no auth.
Note that my plan is to expand the committers/tools listing to include
virtually all cgis - which is restricted to committers, so they won't be
too surprised if they can't auth some tools. Then eventually rewrite
the homepage with a manually curated list of the most used tools.
--
- Shane
https://www.apache.org/foundation/marks/resources
Re: Making Whimsy tools user-friendly and findable
Posted by sebb <se...@gmail.com>.
On 26 May 2017 at 23:34, Shane Curcuru <as...@shanecurcuru.org> wrote:
> I plan to implement some UI and documentation changes to most of the
> *.cgi in /www, to have simple documentation in every page, as well as
> adding some related links to pages. There are a lot of highly useful -
> if not required - tools on Whimsy now, and it would be nice to help
> users find them more easily.
>
> See this example for what I'm doing:
> https://whimsy.apache.org/committers/tools
>
> - "About This Script" would include a short "how-to / what this does"
> blurb for almost all single-cgi tools (I'm not working on /roster or
> board/ tools which have their own UI yet).
>
> - "More Whimsy" will be a manually curated list of related links for
> that page. This will help users find other informational or process
> tools that are available.
>
> - Note the smaller navbar/footer, and the required copyright and ASF
> links now appear in the Apache dropdown menu.
>
> A second task is making the /committers/tools list be comprehensive of
> all the available scripts that Whimsy provides. Since many tools are
> access restricted, I plan to put color-coded glyphicon-lock icons next
> to each URL so there's a hint for people which things they can use.
Remember that some colours cannot easily be distinguished by some people.
Some may even not be able to distinguish colours at all.
So colour should not be the only visually distint quality.
>
> Separately, what do people think about adding Google Analytics to some
> of the major tools & homepage to see how much traffic Whimsy tools get?
> Great Idea / Heck No / OK, Shane, go be crazy if you really want?
>
> --
>
> - Shane
> https://www.apache.org/foundation/marks/resources
Re: Making Whimsy tools user-friendly and findable
Posted by sebb <se...@gmail.com>.
On 27 May 2017 at 03:38, Sam Ruby <ru...@intertwingly.net> wrote:
> On Fri, May 26, 2017 at 10:25 PM, Shane Curcuru <as...@shanecurcuru.org> wrote:
>> Optimization exercise: how would we turn the output of tools/wwwdocs.rb
>> get_annotated_scan(...) into a nightly generated
>> /public/whimsy-tools.json? Side effect: learning more about whimsy
>> architecture.
>>
>> * Inputs (all public files):
>> - /www/**/*.cgi where line =~ ... PAGETITLE = ...
>> -
>> whimsy-vm4.apache.org.yaml['vhosts_whimsy::vhosts::vhosts']['whimsy-vm-443']['authldap']
>>
>> * Output (which would be sucked in by /www/committers/tools.cgi):
>> - /www/public/whimsy-tools.json
>
> Answer to the question asked: you want a cron job. Cron jobs are
> managed by puppet. The file that controls this is here:
>
> https://github.com/apache/infrastructure-puppet/blob/deployment/modules/whimsy_server/manifests/cronjobs.pp
>
> Be sure to read the infra workflow information here before proceeding:
>
> https://github.com/apache/whimsy/blob/master/DEPLOYMENT.md#production-configuration
>
> ---
>
> While the above is the answer to the question asked, a better answer
> would be to add a call to run wwwdocs.rb to the :update task in the
> Rakefile:
>
> https://github.com/apache/whimsy/blob/master/Rakefile#L8
>
> The update task is run any time new code is deployed.
>
> ---
>
>> * Questions:
>>
>> - Why are the scripts that generate /public inside /www/roster, instead
>> of being in /tools? Mere history, or a specific reason?
>
> The initial set of tools were roster related. If you want to move
> them, be sure to update the relevant cronjobs.
>
>> - Does one *need* an ASF::module to wrap the data model, or can the
>> existing generation code in wwwdocs.rb just be used as-is, wrapped in
>> sufficient calls to public_json_common.rb to handle the 'write file only
>> if json data changed' bits?
>
> Either cronjobs or rake tasks can invoke the tool as is.
>
>> - Better suggestions to do this? I know writing the .json to /public
>> maybe premature optimization, but I'm also thinking there might be other
>> uses of this data as well, meaning having a URL with the data is useful.
>
> Cool. It is also useful for debugging (much like the scavenge/analyze
> split in the site tool).
Also HTTP URLs are easy to redirect.
SVN/Git not so easy.
>> --
>>
>> - Shane
>> https://www.apache.org/foundation/marks/resources
>
> - Sam Ruby
Re: Making Whimsy tools user-friendly and findable
Posted by Sam Ruby <ru...@intertwingly.net>.
On Fri, May 26, 2017 at 10:25 PM, Shane Curcuru <as...@shanecurcuru.org> wrote:
> Optimization exercise: how would we turn the output of tools/wwwdocs.rb
> get_annotated_scan(...) into a nightly generated
> /public/whimsy-tools.json? Side effect: learning more about whimsy
> architecture.
>
> * Inputs (all public files):
> - /www/**/*.cgi where line =~ ... PAGETITLE = ...
> -
> whimsy-vm4.apache.org.yaml['vhosts_whimsy::vhosts::vhosts']['whimsy-vm-443']['authldap']
>
> * Output (which would be sucked in by /www/committers/tools.cgi):
> - /www/public/whimsy-tools.json
Answer to the question asked: you want a cron job. Cron jobs are
managed by puppet. The file that controls this is here:
https://github.com/apache/infrastructure-puppet/blob/deployment/modules/whimsy_server/manifests/cronjobs.pp
Be sure to read the infra workflow information here before proceeding:
https://github.com/apache/whimsy/blob/master/DEPLOYMENT.md#production-configuration
---
While the above is the answer to the question asked, a better answer
would be to add a call to run wwwdocs.rb to the :update task in the
Rakefile:
https://github.com/apache/whimsy/blob/master/Rakefile#L8
The update task is run any time new code is deployed.
---
> * Questions:
>
> - Why are the scripts that generate /public inside /www/roster, instead
> of being in /tools? Mere history, or a specific reason?
The initial set of tools were roster related. If you want to move
them, be sure to update the relevant cronjobs.
> - Does one *need* an ASF::module to wrap the data model, or can the
> existing generation code in wwwdocs.rb just be used as-is, wrapped in
> sufficient calls to public_json_common.rb to handle the 'write file only
> if json data changed' bits?
Either cronjobs or rake tasks can invoke the tool as is.
> - Better suggestions to do this? I know writing the .json to /public
> maybe premature optimization, but I'm also thinking there might be other
> uses of this data as well, meaning having a URL with the data is useful.
Cool. It is also useful for debugging (much like the scavenge/analyze
split in the site tool).
> --
>
> - Shane
> https://www.apache.org/foundation/marks/resources
- Sam Ruby
Re: Making Whimsy tools user-friendly and findable
Posted by Shane Curcuru <as...@shanecurcuru.org>.
Optimization exercise: how would we turn the output of tools/wwwdocs.rb
get_annotated_scan(...) into a nightly generated
/public/whimsy-tools.json? Side effect: learning more about whimsy
architecture.
* Inputs (all public files):
- /www/**/*.cgi where line =~ ... PAGETITLE = ...
-
whimsy-vm4.apache.org.yaml['vhosts_whimsy::vhosts::vhosts']['whimsy-vm-443']['authldap']
* Output (which would be sucked in by /www/committers/tools.cgi):
- /www/public/whimsy-tools.json
* Questions:
- Why are the scripts that generate /public inside /www/roster, instead
of being in /tools? Mere history, or a specific reason?
- Does one *need* an ASF::module to wrap the data model, or can the
existing generation code in wwwdocs.rb just be used as-is, wrapped in
sufficient calls to public_json_common.rb to handle the 'write file only
if json data changed' bits?
- Better suggestions to do this? I know writing the .json to /public
maybe premature optimization, but I'm also thinking there might be other
uses of this data as well, meaning having a URL with the data is useful.
--
- Shane
https://www.apache.org/foundation/marks/resources
Re: Making Whimsy tools user-friendly and findable
Posted by Sam Ruby <ru...@intertwingly.net>.
Shane, go be crazy if you really want!
- Sam Ruby
On Fri, May 26, 2017 at 6:34 PM, Shane Curcuru <as...@shanecurcuru.org> wrote:
> I plan to implement some UI and documentation changes to most of the
> *.cgi in /www, to have simple documentation in every page, as well as
> adding some related links to pages. There are a lot of highly useful -
> if not required - tools on Whimsy now, and it would be nice to help
> users find them more easily.
>
> See this example for what I'm doing:
> https://whimsy.apache.org/committers/tools
>
> - "About This Script" would include a short "how-to / what this does"
> blurb for almost all single-cgi tools (I'm not working on /roster or
> board/ tools which have their own UI yet).
>
> - "More Whimsy" will be a manually curated list of related links for
> that page. This will help users find other informational or process
> tools that are available.
>
> - Note the smaller navbar/footer, and the required copyright and ASF
> links now appear in the Apache dropdown menu.
>
> A second task is making the /committers/tools list be comprehensive of
> all the available scripts that Whimsy provides. Since many tools are
> access restricted, I plan to put color-coded glyphicon-lock icons next
> to each URL so there's a hint for people which things they can use.
>
>
> Separately, what do people think about adding Google Analytics to some
> of the major tools & homepage to see how much traffic Whimsy tools get?
> Great Idea / Heck No / OK, Shane, go be crazy if you really want?
>
> --
>
> - Shane
> https://www.apache.org/foundation/marks/resources
Re: Making Whimsy tools user-friendly and findable
Posted by Daniel Gruno <hu...@apache.org>.
On 05/27/2017 12:34 AM, Shane Curcuru wrote:
> I plan to implement some UI and documentation changes to most of the
> *.cgi in /www, to have simple documentation in every page, as well as
> adding some related links to pages. There are a lot of highly useful -
> if not required - tools on Whimsy now, and it would be nice to help
> users find them more easily.
>
> See this example for what I'm doing:
> https://whimsy.apache.org/committers/tools
>
> - "About This Script" would include a short "how-to / what this does"
> blurb for almost all single-cgi tools (I'm not working on /roster or
> board/ tools which have their own UI yet).
>
> - "More Whimsy" will be a manually curated list of related links for
> that page. This will help users find other informational or process
> tools that are available.
>
> - Note the smaller navbar/footer, and the required copyright and ASF
> links now appear in the Apache dropdown menu.
>
> A second task is making the /committers/tools list be comprehensive of
> all the available scripts that Whimsy provides. Since many tools are
> access restricted, I plan to put color-coded glyphicon-lock icons next
> to each URL so there's a hint for people which things they can use.
May I suggest you use a green padlock for the IPMC ones, and not
"another indistinguishable blue one"? ;-)
>
>
> Separately, what do people think about adding Google Analytics to some
> of the major tools & homepage to see how much traffic Whimsy tools get?
> Great Idea / Heck No / OK, Shane, go be crazy if you really want?
>