These are chat archives for ethereum/homestead-guide

15th
Mar 2016
Hudson Jameson
@Souptacular
Mar 15 2016 00:00
Great job @/all . The documentation isn't over, but it's good that we got an MVP-ish thing out on homestead day :)
hughlang
@hughlang
Mar 15 2016 00:01
:thumbsup:
That’s the silly intro I wrote for The Homestead Release :)
Rocky Fikki
@rfikki
Mar 15 2016 00:12
I noticed that the URL works fine for www.ethdocs.org but fails resolving the name if without the www prefix. So, ethdocs.org seems to have a name resolution problem for me.
hughlang
@hughlang
Mar 15 2016 00:13
Ah, i think you have to set the ANAME to @
Viktor Trón
@zelig
Mar 15 2016 00:39
not very happy you released guys
we are in the middle of major reorg
why did you do this really? I assumed we work on consensus here...
never mind
Viktor Trón
@zelig
Mar 15 2016 00:53
i understand you all wanted it for the homestead to be done. but it is not done.
in fact it is in a total messy intermediate temporary state
people start linking to it it will break
it has missing parts and also total nonsense still in glossary etc
this makes me very grumpy - i dont give my name to your v1
Viktor Trón
@zelig
Mar 15 2016 01:58
Ok drama over we did great crisis management :smile:
Back to work
Hudson Jameson
@Souptacular
Mar 15 2016 01:59
Agreed. Vik and I talked offline and we are now on the same page. I removed the announcements and in the future there will be consensus before announcements are made. Sorry for jumping the gun guys, we are all doing great work on this, especially @zelig, and it deserves a proper release announcement once organized and finished.
Viktor Trón
@zelig
Mar 15 2016 02:00
We announce version 1 when ready. Even if it's two weeks/wooks
I also posted links to the doc in some responses on Reddit but added the caveat that it's wip. I think it's prudent that way
Keep up the good work and good spirit
hughlang
@hughlang
Mar 15 2016 02:03
Cool
Bob Summerwill
@bobsummerwill
Mar 15 2016 06:47
I'm very glad to hear it. Sorry, @zelig. Group hug!
Viktor Trón
@zelig
Mar 15 2016 08:08
@rfikki thanks man, see my comments on your PR, please amend and rebase cos I merged #159. Thx
Viktor Trón
@zelig
Mar 15 2016 09:10
guys i have done quite a bit of rereading and thinking and more and more inclined to reinstate the frontier guide principle of vertical topical structuring
this would involve chapters: intro, clients, account management, network, mining, contracts and transactions
the intro would provide horizontal views of the doc: basic usage, developing under ethereum
which would list pointers like noobs track, dapp developers track
Viktor Trón
@zelig
Mar 15 2016 09:16
I would put installing clients under ethereum clients, also making 'why multiple clients' as proper sections
I'd merge dapp development and higher level languges and IDE+contract development tools under contracts&txs like in frontier guide
also blockchain explorers and base layer services
merge test networks under network
still unsure if the current basic-usage/ether should be a separate chapter, probably it should
ecosystem/community and foundation will go to intro
Viktor Trón
@zelig
Mar 15 2016 09:24
what is ethereum would recap ecosystem chapter but only as pointers to within the verticals
and also would be a web3 vision section introducing the notion of dapps, whisper and swarm
The GUIs would be listed within the ethereum clients chapter and referred to from web3 dapp section too
scream ASAP if you feel uncomfortable with any of this
hughlang
@hughlang
Mar 15 2016 11:29
@zelig @Souptacular Might this be a good time to setup a new repo? Possibly for the champions thing? At the very least a branch with its own RTD site.
@zelig I think the Frontier structure is great. However, it is great because it focuses mostly on one thing: geth examples. Not sure how easy it is when you try to inline several other language/platforms.
Hudson Jameson
@Souptacular
Mar 15 2016 11:49
@zelig I echo @hughlang 's concerns. I don't think we want to duplicate frontier's structure because there is so much new material that would make a vertical topical structuring harder to handle.
hughlang
@hughlang
Mar 15 2016 11:51
Also, is it possible to separate the left nav into sections? Perhaps this would provide a nice separation of the topical structure versus the … ethereum 101 structure
they are both valid
Hudson Jameson
@Souptacular
Mar 15 2016 11:53
Agreed. And I think it is possible to separate them in a different way. @zelig I think I would understand your vision/proposal for the structuring more if you wrote it out in a Google doc similar to what we did when we started planning this.
Viktor Trón
@zelig
Mar 15 2016 12:05
i do not understand the concern with geth. I am not planning to put in more geth, just reorg, leaving as much geth or not geth as there already is, it works pretty well
although there is new material a lot of the old material is left out (notably the detailed contract examples) which is alright since it had too much emphasis on console and there are tutorials etc anyway
hughlang
@hughlang
Mar 15 2016 12:12
Nothing wrong with geth at all. geth is great. Just saying it will get crowded when you try to layer in other language examples. Often where the usage examples can be different.
Anyway, I still think it can be done. We should try to preserve parts of the old structure that have value. The stuff i call Ethereum 101. Even if there is redundancy.
hughlang
@hughlang
Mar 15 2016 12:26
I think the C++ guide is fine as-is. As a holistic one-stop shop for that audience. Even if it has much more content than the other clients at this time.
Bob Summerwill
@bobsummerwill
Mar 15 2016 19:16

So yeah, the C++ page really is THE DOCUMENTATION for the C++ client, where the others are just our pointers to documentation maintained by the other client teams.

@zelig Do you think it is possible/desirable for the same kind of documentation migration to happen for the Go client documentation? ie. that all of https://github.com/ethereum/go-ethereum/wiki would be moved under http://www.ethdocs.org/en/latest/ethereum-clients/go-ethereum/go-ethereum.html (and edited with loving care at the same time!) That would be cool, but can obviously only happen if the Go team actually WANT that.

We've made this move for the C++ client because chriseth wanted to do that. He (and I) want the same kind of version history and PR/review workflow and "quality bar aspiration" that we want for the source code. We could make made our own new "readthedocs" guide, as already happened for Solidity, but it seemed pointless to make a new "C++ only guide" when the Homestead Documentation Initiative was happening, so moving all C++ documentation under that banner made perfect sense for us. Not sure if the Go team will have the same feeling/aims, but maybe?

The tension that we have, though, is that we want that C++ documentation to be useful in its own right, and that might mean some redundancy/cut-and-paste between the "main part" of the Homestead docs and the C++ subset. That is fine, but I don't think we have found that balance yet.

WRT to your broad outline suggestion, @zelig, I am not opposed. The challenge is how to make "inlined examples" workable if you want examples in multiple languages. We can't be the first project to hit this, eh? What do Microsoft do for .NET? Where you might have VB.NET, C# or F# examples? Do we need a "toggle" of some kind? Is that even possible? I guess what you really want is a drop-down where the end-user chooses their "language", and that makes the appropriate examples appear. Is that even possible in Sphinx? Or if not, then maybe we do something with putting the examples on their own pages, and have links to them in the main text, ie.

Here is an example of doing X:

  • Link to geth example
  • Link to eth example
  • Link to PyethApp example
  • Link to ethereumjs example
Hudson Jameson
@Souptacular
Mar 15 2016 21:07
I'm under the weather so I'll be out of commission for the next 48 hours.
Bob Summerwill
@bobsummerwill
Mar 15 2016 21:27
Get well soon. I feel like shit too.
My wife and I have both got some horrific cold thing and I feel like am going to puke right now. Yuck.
hughlang
@hughlang
Mar 15 2016 21:38
strangely happening to me too. Not terrible, just uncommon
John Gerryts
@phonikg
Mar 15 2016 21:51
Make that 4 of us... thats what lack of sleep preparing for a Homestead release does to you...