Merge pull request #356 from protofire/feature/help-text-update

Update help texts

src/components/Home/Charts/GiniChart.tsx

@@ -2,8 +2,7 @@ import React from 'react'
 import { Line, YAxis } from 'recharts'
 import { Chart, ChartWrapper } from '../../common'
 
-const info =
-  'Allows us to keep track of how ‘fair’ the distribution of voting tokens is in the MKR governance ecosystem.'
+const info = `This tile shows the Gini coefficient (a measure of distribution inequality) of MKR locked in the DSChief governance contract. This allows governance to judge how ‘equal’ the distribution of voting tokens is in the MKR governance ecosystem. <br> For each unique address the total MKR locked into the DSChief is calculated for each date period using the Lock and Free events emitted by the DSChief contract. Then the Gini coefficient is calculated using the distribution of MKR across addresses for each of those date periods. <br> <strong>Note that the Gini coefficient in this metric is calculated on MKR held within DSChief only, not the total distribution.</strong>`
 const links = [
   {
     title: 'MakerDAO Governance Graph',
@@ -14,7 +13,7 @@ const links = [
 const GiniChart = props => {
   const { wrapperProps, modalProps } = props
   return (
-    <ChartWrapper info={info} links={links} {...wrapperProps}>
+    <ChartWrapper markdown info={info} links={links} {...wrapperProps}>
       <Chart {...modalProps}>
         <YAxis />
         <Line

src/components/Home/Charts/MkrDistributionPerExecutiveChart.tsx

@@ -3,8 +3,7 @@ import { Bar, Cell, YAxis } from 'recharts'
 import { Chart, ChartWrapper } from '../../common'
 import { CustomSvg } from '../../common/Icon'
 
-const info =
-  'This metric helps to inform governance of the distribution of MKR within the governance system and which executive has the current hat and the amount of MKR staked on the current hat.'
+const info = `This tile shows the distribution of staked MKR over executive proposals ordered by date. This informs governance as to the distribution of MKR within DSChief and denotes clearly which executive currently has the ‘hat.’ <br> This metric is generated using the Lock and Free events emitted by the DSChief contract. For each executive proposal the Freed MKR is summed and subtracted from the summed Locked MKR to get the current amount of MKR staked on each executive proposal. This total value is then displayed on the graph as a bar ordered by the executive creation date. Finally the ‘hat’ executive is coloured dark grey to separate it from the other executives.`
 const links = [
   {
     title: 'MakerDAO Governance Graph - Executives',
@@ -38,7 +37,7 @@ const MkrDistributionPerExecutiveChart = props => {
   const { wrapperProps, modalProps } = props
   const maxValue = Math.max(...modalProps.data.map(o => o.mkr), 0)
   return (
-    <ChartWrapper info={info} links={links} {...wrapperProps} hideFilters>
+    <ChartWrapper markdown info={info} links={links} {...wrapperProps} hideFilters>
       <Chart {...modalProps} showXaxis={3} legend={renderLegend}>
         <YAxis style={{ fontSize: '12px' }} type="number" domain={[0, maxValue]} />
         <Bar isAnimationActive={modalProps.data ? false : true} name={'Executive vote'} dataKey="mkr">

src/components/Home/Charts/StakedMkrChart.tsx

@@ -4,8 +4,7 @@ import { Line, YAxis } from 'recharts'
 import { Chart, ChartWrapper, LegendLi } from '../../common'
 import { CustomSvg } from '../../common/Icon'
 
-const info =
-  'Being able to see voter participation over time allows us to judge the safety and representativeness of the current set of system parameters.'
+const info = `This tile shows MKR participation in voting over time. This allows governance to judge the current and historic safety of the system and the representativeness of the current set of system parameters. <br> Total MKR is calculated by summing all mint and burn events for the MKR token and displaying the summed value at each date on the graph. <br> Staked MKR is calculated by summing the MKR locked in the DSChief governance contract (denoted by the emitted Lock event) and subtracting the MKR unlocked from the DSChief governance contract (denoted by the emitted Free event). <br> Voting MKR is calculated by looping over each Vote event and summing the MKR if it is a positive vote, and subtracting it if it is a vote for ‘no proposal’. MKR removed from the Chief (denoted by Free events) is deducted from this total.<br> Non-Voting MKR is calculated by subtracting the value for Voting MKR from the value for Staked MKR.`
 const links = [
   {
     title: 'MakerDAO Governance Graph',
@@ -50,7 +49,7 @@ const StakedMkrChart = ({ wrapperProps, modalProps }) => {
   }
 
   return (
-    <ChartWrapper info={info} links={links} {...wrapperProps}>
+    <ChartWrapper markdown info={info} links={links} {...wrapperProps}>
       <Chart legend={renderLegend} getOpacity={getOpacities} handleLegend={selectLine} {...modalProps}>
         <YAxis type="number" domain={[0, 'dataMax']} />
         <Line

src/components/Home/Charts/TimeTakenChart.tsx

@@ -2,7 +2,7 @@ import React from 'react'
 import { Bar, YAxis } from 'recharts'
 import { Chart, ChartWrapper } from '../../common'
 
-const info = 'This distribution gives users an idea of how long a given executive takes to pass. '
+const info = `This tile shows the average amount of time that passes between an executives proposals creation and its execution. This can be used to estimate the time it will take for a non-controversial executive to pass, and also used as a metric to determine how aligned MKR Token Holders are. <br> Each executive proposal is collected by tracking events emitted by DSChief and calculating the number of blocks between the creation block of each executive proposal, and the ‘cast’ block of each executive spell. This block difference is then converted into standard time and each executive is dropped into the appropriate bucket. The count of executive proposals in each bucket is then displayed. <br> <strong>Note that this tile does not track executives that have never been cast, or executives that were cast more than 30 days after their creation.</strong>`
 const links = [
   {
     title: 'MakerDAO Governance Graph',
@@ -14,7 +14,7 @@ const TimeTakenChart = props => {
   const { wrapperProps, modalProps } = props
 
   return (
-    <ChartWrapper info={info} links={links} {...wrapperProps} hideFilters>
+    <ChartWrapper markdown info={info} links={links} {...wrapperProps} hideFilters>
       <Chart {...modalProps}>
         <YAxis />
         <Bar

src/components/Home/Charts/VotersVsMkrChart.tsx

@@ -2,7 +2,7 @@ import React, { useState } from 'react'
 import { Line, YAxis } from 'recharts'
 import { Chart, ChartWrapper } from '../../common'
 
-const info = 'Gives a general overview of the state of the system in terms of both token and address engagement.'
+const info = `This tile shows participation in MKR governance over time. This gives governance a general overview of the state of the system in terms of both MKR and address engagement.<br> Total MKR Staked is calculated by summing the MKR locked in the DSChief governance contract (denoted by the emitted Lock event) and subtracting the MKR unlocked from the DSChief governance contract (denoted by the emitted Free event.) <br> Number of voters is calculated by summing all uniques voting addresses in DSChief and displaying the summed value at each date on the graph. <br> <strong>Note that this tile does not track decreases as voting addresses withdraw their MKR from DSChief.</strong>`
 const links = [
   {
     title: 'MKR Registry Graph',
@@ -16,7 +16,7 @@ const VotersVsMkrChart = props => {
   const { wrapperProps, modalProps } = props
   const getOpacities = opacities => setOpacities(opacities)
   return (
-    <ChartWrapper info={info} links={links} {...wrapperProps}>
+    <ChartWrapper markdown info={info} links={links} {...wrapperProps}>
       <Chart getOpacity={getOpacities} {...modalProps}>
         <YAxis yAxisId="0" datakey="count" />
         <YAxis yAxisId="1" datakey="mkr" orientation="right" />

src/components/Home/Charts/VotesVsPollsChart.tsx

@@ -2,8 +2,8 @@ import React from 'react'
 import { Line, YAxis } from 'recharts'
 import { Chart, ChartWrapper } from '../../common'
 
-const info =
-  'Being able to see the rate of change of votes and polls over time lets us judge the demand on governance over time.'
+const info = `This tile shows the number of executive proposals and polls that have been created over time. This allows governance to judge how the rate of increase has changed over time, which can be used as an approximation for the time-cost of governance. <br> Executive Votes total is calculated by counting each unique contract address that a MKR holder has voted for and displaying the count of those unique contract addresses at each date on the graph. <br> Polls total is calculated by counting the number of CreatePollAction events generated by the PollingEmiter contract and displaying that count value at each date on the graph.
+`
 const links = [
   {
     title: 'MakerDAO Governance Graph',
@@ -14,7 +14,7 @@ const links = [
 const VotesVsPollsChart = props => {
   const { wrapperProps, modalProps } = props
   return (
-    <ChartWrapper info={info} links={links} {...wrapperProps}>
+    <ChartWrapper markdown info={info} links={links} {...wrapperProps}>
       <Chart {...modalProps}>
         <YAxis datakey="countPolls" />
         <Line

src/components/Home/HomeDetail.tsx

@@ -169,8 +169,7 @@ function HomeDetail(props: Props) {
       polls: {
         data: recentPolls,
         columns: expanded => pollcolumns(expanded),
-        info:
-          'This gives governance a brief overview of the most recent polls, and serves as a navigation aid for users to explore further.',
+        info: `This tile shows a short list of the most recent polls and the amount of time left with which to vote. It serves as a navigation aid for users to explore further. <br> This list is generated using the PollCreated event emitted by the PollingEmitter contract. Each poll that is created is sorted by creation date and the top five most recently created polls are displayed.`,
         links: [
           {
             title: 'MakerDAO Governance Graph',
@@ -185,8 +184,7 @@ function HomeDetail(props: Props) {
       votedPolls: {
         data: mostVotedPolls,
         columns: votedPollcolumns,
-        info:
-          'This allows governance to get an idea of the most popular decisions made in the history of MKR Governance. It also provides a baseline expectation of participation.',
+        info: `This tile shows the polls that have gathered the most MKR participation in the history of Maker Governance. As well as showing as a historical record, it also gives governance an idea of how much participation to expect, and a target level of participation to beat. <br> This list is generated by calculating the amount of MKR voting for each poll at the time it closed using Voted events emitted by the PollingEmitter contract. Each value is then divided by the total MKR supply and this value is formatted as a percentage. This list is then sorted by participation percentage and displayed.`,
         links: [
           {
             title: 'MakerDAO Governance Graph',
@@ -208,8 +206,7 @@ function HomeDetail(props: Props) {
       executives: {
         data: data.executives.sort((a, b) => Number(b.approvals) - Number(a.approvals)),
         columns: expanded => executiveColumns(expanded),
-        info:
-          'Lets users see how MKR is currently distributed over executive votes, giving some idea of the value of the current hat, and where ‘idle’ MKR is sitting in the system.',
+        info: `This tile shows the executive proposals that have the most MKR staked. This allows governance to see how MKR is currently distributed within the DSChief contract. This gives some idea of the value of the current hat, the security of the system, and where ‘idle’ MKR is sitting in the system.<br> This metric is calculated by using the Lock, Free and the Etch (vote) events emitted by the DSChief contract to sum the amount of MKR currently voting for each executive proposal. Each executive proposal is then sorted by the amount of MKR staked and displayed.`,
         links: [
           {
             title: 'MakerDAO Governance Graph',
@@ -223,8 +220,7 @@ function HomeDetail(props: Props) {
       },
       topVoters: {
         data: topVoters.sort((a, b) => Number(b.count) - Number(a.count)),
-        info:
-          'A list of the addresses that have voted the most in the MKR governance system. Having a ‘leaderboard’ will hopefully lead to more active and consistent participants in the voting ecosystem.',
+        info: `This tile shows a list of the addresses that have voted the most in the MKR governance ecosystem. It is hoped that having a ‘leaderboard’ will incentivise voters to become more active and consistent within the voting ecosystem. <br> To calculate this metric we use the Vote event emitted by the DSChief contract and the Voted event emitted by the PollingEmitter contract to get all vote events. We then tally the number of polls and executives voted on by each address. This count is then sorted and the top five addresses are displayed.`,
         links: [
           {
             title: 'MakerDAO Governance Graph - Executives',
@@ -243,8 +239,7 @@ function HomeDetail(props: Props) {
           .filter(vote => !vote.casted && differenceInMonths(new Date(), fromUnixTime(vote.timestamp)) < 12)
           .sort((a, b) => Number(b.approvals) - Number(a.approvals)),
         columns: uncastedExecutiveColumns,
-        info:
-          'This metric helps to inform governance of potentially malicious MKR being moved to old uncast executive votes.',
+        info: `This tile shows a list of the executive proposals that have never been ‘cast’ (passed and become active in the system.) This allows governance to become aware of any malicious MKR being moved to old uncast executive proposals. <br> This list is generated by checking all executive proposals and checking their ‘casted’ property to determine whether they have ever been cast. Those that haven’t are sorted by the amount of MKR staked on each proposal and displayed. <br> <strong>Note that this metric only displays uncast executives created in the last twelve months.</strong>        `,
         links: [
           {
             title: 'MakerDAO Governance Graph',
@@ -511,7 +506,7 @@ function HomeDetail(props: Props) {
     const data = getComponentData('table', props.component, props.content, props.expanded)
 
     return (
-      <StrippedTableWrapper info={props.info} links={props.links} {...getWrapperProps(data)}>
+      <StrippedTableWrapper markdown info={props.info} links={props.links} {...getWrapperProps(data)}>
         <Table sortBy={props.sortBy} {...getModalProps(data.type, data.component, data.expanded, props.handleRow)} />
       </StrippedTableWrapper>
     )

src/components/PollDetails/Charts/MakerDistributionChart.tsx

@@ -4,8 +4,7 @@ import { defaultColors } from './'
 import { Chart, ChartWrapper, LegendLi } from '../../common'
 import { CustomSvg } from '../../common/Icon'
 
-const info =
-  'Shows the historical amount of MKR voting for each option in this poll. This helps track swings in opinion over time, as well as allowing comparison between the ‘Vote Count By Option’ metric.'
+const info = `This tile shows the current and historical amount of MKR voting for each option in this poll. This allows governance to track swings in opinion over time, as well as allowing comparison between the ‘Vote Count By Option’ tile. <br> This metric is generated using the Voted event emitted by the PollingEmitter governance contract. We keep track of the MKR balance of each voting address over the time of the poll, and for each emitted Voted event apply it to the voted option. These summed values are then displayed.`
 const links = [
   {
     title: 'MKR Registry Graph',
@@ -51,7 +50,7 @@ const MakerDistributionChart = props => {
     )
   }
   return (
-    <ChartWrapper info={info} links={links} {...wrapperProps} hideFilters>
+    <ChartWrapper markdown info={info} links={links} {...wrapperProps} hideFilters>
       <Chart legend={renderLegend} getOpacity={getOpacities} handleLegend={selectLine} scale="point" {...modalProps}>
         <YAxis type="number" domain={[0, 'dataMax']} />
         {options.map((option, i) => (

src/components/PollDetails/Charts/PollPerOptionChart.tsx

@@ -18,8 +18,8 @@ const PollPerOptionChart = props => {
   const chartColors = [...defaultColors, ...colors]
 
   const info = isVoter
-    ? 'Shows the current or final distribution of voting addresses across the options available in this poll. This gives an intuitive visual depiction of the current or final vote results in terms of addresses.'
-    : ' Shows the current or final distribution of MKR voting across the options available in this poll. This gives an intuitive visual depiction of the current or final vote results in terms of MKR.'
+    ? `This tile shows the current or final distribution of voting addresses across the options available in this poll. This gives an intuitive visual depiction of the current or final vote results in terms of addresses.`
+    : `This metric is generated using the Voted event emitted by the PollingEmitter governance contract. The most recent Voted event for each unique address is placed into a bucket based on the option for which it voted. The address count for each option bucket is then displayed.`
   const links = !isVoter
     ? [
         {

src/components/PollDetails/Charts/VotersDistributionChart.tsx

@@ -4,8 +4,7 @@ import { defaultColors } from './'
 import { Chart, ChartWrapper, LegendLi } from '../../common'
 import { CustomSvg } from '../../common/Icon'
 
-const info =
-  'Shows the historical number of addresses voting for each option in this poll. This helps track swings in opinion over time, as well as allowing comparison between the ‘MKR Count By Option’ metric.'
+const info = `This tile shows the current and historical number of addresses voting for each option in this poll. This allows governance to track swings in opinion over time, as well as allowing comparison between the ‘MKR Count By Option’ tile. <br> This metric is generated using the Voted event emitted by the PollingEmitter governance contract. For each emitted event, we track the voting address and the voted option. For each data point, we then count the number of addresses that have voted for each option. These counts are then displayed.`
 const links = [
   {
     title: 'MakerDAO Governance Graph',
@@ -52,7 +51,7 @@ const VotersDistributionChart = props => {
   }
 
   return (
-    <ChartWrapper info={info} links={links} {...wrapperProps} hideFilters>
+    <ChartWrapper markdown info={info} links={links} {...wrapperProps} hideFilters>
       <Chart legend={renderLegend} getOpacity={getOpacities} handleLegend={selectLine} scale="point" {...modalProps}>
         <YAxis />
         {options.map((option, i) => (

src/components/PollDetails/index.tsx

@@ -278,9 +278,8 @@ function PollDetails(props: Props) {
         </CardStyled>
         <CardStyled style={{ padding: 0 }}>
           <StrippedTableWrapper
-            info={
-              'A leaderboard for the top MKR supporters on this poll. Allows easy navigation to those addresses voting history and etherscan address. '
-            }
+            markdown
+            info={`This tile shows a leaderboard for the largest MKR holders that have voted in this poll. This is primarily a navigational tool that provides access to each address’s voting history and etherscan address. <br> This metric is generated using the Voted event emitted by the PollingEmitter governance contract. The total MKR held by each address voting in this poll is counted and added to this list. This MKR value is then converted into a percentage of the total MKR voting in this poll. This list is then sorted large to small and displayed.`}
             links={[
               {
                 title: 'MakerDAO Governance Graph',