These are chat archives for ethereum/homestead-guide

7th
Jan 2016
Hudson Jameson
@Souptacular
Jan 07 2016 04:23
Should the guide be exclusive to Geth or also include instructions for eth/Aleth clients?
Hudson Jameson
@Souptacular
Jan 07 2016 05:48
@all Please review and contribute to this Homestead Documentation Planning Google Doc. You can leave comments or directly edit (for now). Although we will soon formally ask the community for help by assigning specific sections to people, feel free to put your name down if you feel like tackling a topic from the guide. Just add your name in brackets by the topic. By this weekend (or earlier if possible) we should have a clear understanding of how the guide will be organized and we can start porting from the old guide/writing :D
Viktor Trón
@zelig
Jan 07 2016 09:22
great stuff. I really do not like letters in the sectioning please.
I recommended a chapter 'the ethereum ecosystem' for chapter 5-6. see above.
the content should not be dictated by whether it is contributed by the community or devs
the community section (probs not chapter) should only list irc, gitter, reddit, etc entrypoints
dapp resources etc should be in developing on ethereum
i will come with more comments
Fabian Vogelsteller
@frozeman
Jan 07 2016 09:34
if i see that right then 90% is the same as the old guide, right?
where would we write that, in order to prevent writing things in two places (wiki/guide).
Can we still import e.g. the JS api from the wiki? (Which i think we should only LINK, so people always get to see the most up to date version, which can somtimes be very important, if we do breaking changes.)
Viktor Trón
@zelig
Jan 07 2016 13:59
Yes but I would like that most up to date version to be the relevant rst doc (it is editable directly like wiki same but better
Fabian Vogelsteller
@frozeman
Jan 07 2016 14:23
i’m not so convinced that people want to look in two places, the wiki is already the goto place for docs. And the advantage is that everybody can edit it with a github account (which every developer already has).
Look what happened to docs.ethereum.org, this went nowhere
for a tutorial like book, it may make sense, but for APIs? not sure. (given the fact, that you would need to make people look somewhere else)
if we can really do make them change, it may be good, but then we have an outdated and left over wiki, which creates even more confusion
Taylor Gerring
@tgerring
Jan 07 2016 14:30
the docs website went nowhere because there was no buy-in from the development teams, it was just dropped in our laps as an API explorer
I dorm particularly want to spend a long time deciding how to put the guide together, so maybe first we should determine who the target audience is and what solution it intends to provide
then I think picking a publishing method will be more clear
Fabian Vogelsteller
@frozeman
Jan 07 2016 14:32
we could have a better api page, thats for sure, but at least the js api and rpc api hold out quite long and is the main reference point
but i agree, thinking first about who will read this is a good idea ;)
Hudson Jameson
@Souptacular
Jan 07 2016 15:14

@frozeman: I agree the homestead docs should not be an all encompassing entity. Ethereum has many, many areas, and stuff like the intimate details of the APIs may be better placed on the wiki or in the repos that develop those APIs.
@tgerring : My opinion is this guide should be for people who have never heard of Ethereum, heard about the homestead update, and want to do 2 things: Use Ethereum and/or develop on Ethereum. What that means is we need to have a section for "using Ethereum", which is a combination of basic information with examples (like dealing with accounts, sending ether, and interacting with a DApp) and a "developing using Ethereum" with details on creating, compiling, and deploying a contract. There will be more detailed short tutorials/examples in the development section of the guide, and anything beyond the basics can be directed to the new Solidity documentation or areas of the Web3 JS wiki.

This guide should serve to be an entry level for Ethereum users and developers who have to scramble around multiple resources for the most up to date information. I think of it as a checkpoint of updates and better examples/context compared to the previous checkpoint, the Frontier Guide.

Viktor Trón
@zelig
Jan 07 2016 15:34
thanks huds, I coolant
Couldn't* put it better
Although the target audience would be more inclusive if you ask me
I for one often went to the guide to find some info and I'm not exactly the audience huds described :)
Hudson Jameson
@Souptacular
Jan 07 2016 15:57
Appreciate it. And yeah, you aren't the "typical audience" as core devs, but we need to create the docs with the intention of growing Ethereum's usage and application development to the general public. The biggest deterrent of developers is lack of a concrete, well written entry point.
I guess I make this distinction to say that the wiki docs should have a well defined purpose as well as the guide. IMO the guide should be for the purpose of showing someone who wants to use or develop on Ethereum what they need to do (rather than traversing 3+ wiki docs on separate repos), while the wiki documents should be scaled back to include less general content and more specific content to the repos and Ethereum related applications and interfaces that may not need to be fully expressed in the guide. It is a good idea to aim for little to no duplication between the guide and the more specific Ethereum wiki topics.
@frozeman @zelig @tgerring : Do you agree about the intended audience and purpose? If not, what are other options? I feel as though my suggestion is missing something, but I can't put my finger on it.
Fabian Vogelsteller
@frozeman
Jan 07 2016 15:59
i fully agree with this.
Hudson Jameson
@Souptacular
Jan 07 2016 16:00
:+1:
Fabian Vogelsteller
@frozeman
Jan 07 2016 16:01
I also would say, that once the guid proofs useful and rtd works (means many people go there to look things up). Then we could think about moving APIs over etc.
but before we should rather not try to move all things (again).
first test it in the wild using the guide and then see
Hudson Jameson
@Souptacular
Jan 07 2016 16:08
Good call. I do think that we should edit the wiki's to eliminate old info and information that is duplicate. But a full transfer should not begin to happen unless the new guide holds as an often used resource
Fabian Vogelsteller
@frozeman
Jan 07 2016 16:14
yes
i agree to removing old stuff, or at least putting
“OUTDATED” on the top and removing it from the main menues
this is something i will do tomorrow
Hudson Jameson
@Souptacular
Jan 07 2016 16:16
Thanks @frozeman . That will help a lot. I am swamped at my "real" job until Saturday :P
I said "real" job because I do blockchain and Ethereum research/dev at my real job, so I consider hanging out in Gitter part of my work, lol
Viktor Trón
@zelig
Jan 07 2016 19:51
surprise surprise I disagree :)
see the https://github.com/ethereum/homestead-guide. The wiki pages could and should be kept and annotated with links to the corresponding new doc meaning, legacy links are not gonna be dead end. On the other hand, we see that this documentation/publishing infrastructure does everything wiki can do but better, so just use it. Counterarguments?
Viktor Trón
@zelig
Jan 07 2016 19:57
Surely this does not mean we necessarily got to give up the wiki, since it is still good for one-off technical summaries, or in-progress notes for later docs, etc etc
but the parts that should be in the docs, should be in the docs, e.g, all API docs.
so @frozeman yes, the way i dreamed this up is the wiki will stay, but will be converted to sphinx api and included in the book . This means I kindof prefer if the API doc primary source was the rst for rpc2 (the management API needs to be rewritten for rpc2 service structure anyway).
Fabian Vogelsteller
@frozeman
Jan 07 2016 21:00
The rpc docs won't change much for the new rpc. So no rewrite necessary.
We can talk more tomorrow
Viktor Trón
@zelig
Jan 07 2016 21:05
yeah only module structure in management api, but thats quite a lot (crossreferences etc)
Hudson Jameson
@Souptacular
Jan 07 2016 21:11
A good in between would be to keep with the goal of the guide, keep the wiki pages where they are, and then transfer the wiki pages in the middle of homestead once we can gauge popularity of the sphinx format and usage
Viktor Trón
@zelig
Jan 07 2016 21:21
so my problem is:
  • you duplicate content which is not maintainable OR
  • have a link to the wiki . But that would mean most popular content would still go to the wiki, making the shiny new format pointless OR
  • at least for explicitly duplicate parts, use the new rst, and put link to it from wiki (marked as legacy)
Hudson Jameson
@Souptacular
Jan 07 2016 21:35

So the homestead document's purpose would be to be an entry point for all ethereum users and developers and not overly specific or overly technical details. Anything that is specific (for example: certain aspects or details of web3 that devs will likely not even need to use in their general DApp programming or the technical details of ET Hash/how tries are implimented) would stay on the wiki with the possibility of linking to them from the homestead guide. Additionally, things that are not ready for homestead yet, like Whisper and much of the serenity details, will stay on a wiki or independent format. If the document's prove to be successful in this format and we agree to expand it, we can then make a decision to move or not to move the specific data to the guide.

To address the duplication concern: duplicate information should be kept at a minimum and we can do that for most of the information by either adding a "LEGACY" notice to the non-maintained pages with a link to the homestead guide or editing the wikis to remove the material that is a direct copy/paste of homestead guide.

I think we are almost on the same page with the strategy and it mainly comes down to what to do with how to provide that bridge and clear separation between the wiki (specific/technical) content and the homestead guide. As long as we use our purpose statements for each area, we should be mostly fine IMO.
Purpose of Homestead Guide:
  • Entry point for Ethereum Users and Developers (nothing that is incredibly technical or not used in common interactions with DApps)
Purpose of Wiki:
  • House information specific to highly technical/research topics, serve as an archive of old information from previous POCs and ideas of Ethereum development, suppliment the homestead material in very specific ways that are determined "uncommon" for the average Ethereum developer to run into.