Beanstalk Notion
Beanstalk Notion
🏹

Process guide on updating the whitepapers

Status
Done
Assigned
guy

Notes

  • This guide has where to change the PDFs when the whitepaper is updated
  • But we need a guide on comparing PDFs, updating the version history, etc.

Rules

  1. You don’t want to use a term that isn’t defined. In the case of fixed pod order and dynamic pod order, the question is whether or not they need to be defined. If so, you need to explicitly say what they are. Otherwise, don’t bother mentioning them by name. In this case probably makes sense to define fixed and dynamic listings

Verbiage Rules

  • English Sentences end with periods
  • minimal words used without any loss of necessary information
  • do not explain why or how. Explain what is.
  • Do a PDF compare (https://draftable.com/compare) with current version and draft version to confirm no changes are missed in the changelog
  • Always do a final formatting walkthrough to confirm
  • paragraphs are never cut off in middle by a page break
  • sections are nicely ordered by page
  • no huge blank spaces
  • don’t over crunch text together
  • image sizes are consistent and optimal
  • Oxford commas or optional, depending on clarity. Typically don’t need
  • “Can” is better than “must”
  • Make sure all Beanstalk terms are italicized
  • Make sure all code is in code formal

Version history

  • mimic language patters from previous changes; do not ad lib.

Footer / Links Rules

the first instance BIPs are referenced should have a footnote and link - in the example you put BIP-0 doesn't need a footer reference because it is already in the footnotes in an earlier part of the whitepaper. - \footnote creates a footnote -> if you click the number it takes you to where the footnote is located (doesnt take you to another link) - \href links you to the specified link but you can customize the link - i.e. you can put any link and the put a vanity or summarized description if you really wanted to. (example - you can link BIP-2 to the BIP-2 markdown with the following:

\href{https://github.com/BeanstalkFarms/Beanstalk-Governance-Proposals/blob/master/bip/bip-02-tax-efficiency-weather-changes.md}{BIP-2}

- \fref is a command for href without the http -> you can replace the \footnote\hrefs with \frefs if you'd like

\newcommand{\fref}[1]{\footnote{\href{http://#1}{#1}}}
\setlength{\footnotemargin}{8mm} % Spacing between footnote number and body