Whitepaper Standards
- Bobbi Muscara
- enderkaragul
- David Boswell
Please Copy and Use this template when developing a White paper for Hyperledger. Google doc White paper Template
Here is a copy of the HYPERLEDGER WHITE PAPER
Steps to follow when a SIG (or WG too?) is working on writing a whitepaper.
- Send group whitepaper template to use as a starting point
- Review and copy edit before publishing
- Post on Publications page
- Plan social media posts
- Create home page banner
- Invite Chair to TSC call to discuss (if paper is technical)
- Announce whitepaper (and TSC discussion if one is happening) on MC call
Contributed by Gordon Graham 4-8-2019
White Paper Template
Hyperledger [title, as few words as possible]
Purpose of This Paper
[State the main purposes(s) of the document in just a couple of sentences.]
[If something is NOT covered that a reader might reasonably expect to find here, say so. From then on, use the construction... “Any further discussion of (said topic) is beyond the scope of this document.”]
Intended Audience
[state the intended audience as precisely as possible. For most white papers, this will be a technical audience, not a business audience. Does their level of technical understanding matter? Are there some matters they should already understand before they can get anything from the current document? Can we point them to this kind of prerequisite information? Does it matter which framework(s) they are using: Fabric, Indy, Sawtooth, etc? Does it matter what issue they are trying to understand: security, interoperability, etc?]
Table 1: Summary of Hyperledger Frameworks 7
VN.N published [month, year].
This work is licensed under a Creative Commons Attribution 4.0 International License
creativecommons.org/licenses/by/4.0
Acknowledgements
[list all the contributors to the white paper in alphabetical order by LAST name. Many working groups keep a list of members or contributors on their wiki pages or their minutes. Don’t include anyone’s name without their okay.]
Introduction
This white paper explains... [start with a brief topic sentence that sums up what’s in the document. This section “tells them what you’re going to tell them.”]
[In this section, provide a high-level introduction to the topic being covered. If the main body of the white paper will cover four different topics, name them each here, and point to the section where they are considered in more detail.]
[This section doesn’t have to be written first, but it must be filled in before the publication is complete. This helps readers understand the scope of the white paper and whether it’s worth their time to read the entire publication.]
1.1 subsection--topic 1
[If needed, break up the Introduction in subsections. Always have at least 2 subsections, 1.1 and 1.2 or else this numbering system looks unnecessary.]
1.2 subsection--topic 2
[same as above]
1.3 subsection--topic 3
[same as above, if needed]
[Add a page break at the end of the Introduction]
Title for topic 1
[Start this section with a brief paragraph that describes what’s in this section. This helps readers know if they need to read this or they can skip it to go onto another topic they’re more interested in.]
[If this section introduces some vocabulary or some fundamental concepts they need to understand before they can benefit from the following sections, say so right at the start.]
If you need to list several points, consider using a set of bullets:
Item 1
Item 2
Item 3
[By default, list items in alphabetical order. if you prefer to use some order, state it: in order of size, in order by first on the market, and so on.]
2.1 subsection--topic 1
[If needed, break this section up in subsections. Always have at least 2 subsections, 2.1 and 2.2 or else this numbering system looks unnecessary.]
2.2 subsection--topic 2
[same as above]
2.3 subsection--topic 3
[same as above, if needed]
[Add a page break at the end of this section]
Title for topic 2
[Start this section with a brief paragraph that describes what’s in this section. This helps readers know if they need to read this or they can skip it to go onto another topic they’re more interested in.]
[To include a diagram, insert the diagram right into the GDoc. Then give it a number (Figure 1, Figure 2, etc.) and a short, clear title and then reference it in the text:
As shown in Figure 1, the Hyperledger Greenhouse incubates a number of different frameworks (on the top level) and tools (on the bottom level).]
[When the white paper is prepared for publication, the designer can recreate the graphic to look nicer and use the Linux Foundation color scheme.]
FIGURE 1: THE HYPERLEDGER GREENHOUSE STRUCTURE
[Add a page break at the end of this section]
Title for topic 3
[Start this section with a brief paragraph that describes what’s in this section. This helps readers know if they need to read this or they can skip it to go onto another topic they’re more interested in.]
4.1 subsection--topic 1
[If needed, break this section up into subsections. Always have at least 2 subsections, 4.1 and 4.2 or else this numbering system looks unnecessary.]
4.2 subsection--topic 2
[same as above]
4.3 subsection--topic 3
[same as above, if needed]
[Add a page break at the end of this section]
Title for topic 4
[Start this section with a brief paragraph that describes what’s in this section. This helps readers know if they need to read this or they can skip it to go onto another topic they’re more interested in.]
5.1 subsection--topic 1
[To include a table, create the table right in the GDoc. You can use the table below as a starting point. Give it a number (Table 1, Table 2, etc.) and a short, clear title and then reference it in the text:
As shown in Table 1, different Hyperledger frameworks have different purposes. You can see more about each framework in the section shown.]
[When the white paper is prepared for publication, the designer will recreate the table to look nicer and use the Linux Foundation publication template.]
Table 1: Summary of Hyperledger Frameworks
FRAMEWORK | BRIEF DESCRIPTION | SEE ALSO |
HYPERLEDGER FABRIC | A platform for building distributed ledger solutions with a modular architecture that delivers a high degree of confidentiality, flexibility, resiliency, and scalability. This enables solutions developed with Hyperledger Fabric to be adapted for any industry. | 6.2 |
HYPERLEDGER SAWTOOTH | A modular platform for building, deploying, and running distributed ledgers. Sawtooth features a new type of consensus, proof of elapsed time (PoET) which consumes far fewer resources than proof of work (PoW). | 6.3 |
5.2 subsection--topic 2
[same as above]
5.3 subsection--topic 3
[same as above, if needed]
[Add a page break at the end of this section]
Conclusions
This white paper explained... [sum up the white paper briefly. This section “tells them what you told them.” Although this may seem repetitive, some people flip to the back of a document to see “the bottom line” and what they might have missed.]
Further Resources
[In this section, list any further resources or interesting reading that might illuminate the topic more. Include enough detail so that a reader could easily locate that source, including URLs if appropriate.]
Notes
[Although GDocs can’t do Endnotes, the designer will move all your footnotes here. In every footnote, provide the AUTHOR(s), the article or document TITLE, the PUBLISHER, the DATE, and if you have it, the PAGE NUMBER. For a website, include the URL and RETRIEVED ON DATE.]
comments:
White Paper Template
Just a few thoughts from Gordon
should contain standard front matter: Title page, About Hyperledger, About This Paper, Contents, Version number and Publication Date, Creative Commons notice, Acknowledgements, About the Working Group sponsor...
should explicitly define the audience, scope and purpose in the front matter
should probably use a numbering system to help organize the contents
should start with an introductory overview of the topics to be covered, and then move into the details of various topics
should use a recognized rhetorical approach when necessary: for example, move-from-the-familiar-to-the-unfamiliar, or compare-and-contrast
should list items in alphabetical order by default; if using any other ordering system, should explicitly state which (by chronology, location, platform, size and so on)
should contain standard back matter: Conclusions, Appendixes, Further Resources, References
should be prepared in Gdocs, not LaTex nor any other formatting language or system
should not require using Github to avoid unnecessary overhead and version control confusion