These are chat archives for ethereum/homestead-guide

8th
Jan 2016
Viktor Trón
@zelig
Jan 08 2016 03:54 UTC
This sounds good to me. But let's be clear api docs belong to the first category right?
Taylor Gerring
@tgerring
Jan 08 2016 04:01 UTC
we shoudl be clear about what "API" means
i think it was good we did the RPC API page and we owe @frozeman a great round of appluase for his hard work there
but i think all our implemetnatiosn are way too young to declare public APIs for our codebases
CPP just underwent a massive repo restructuring. Go is poised for a major refactoring soon
there's just way too much churn to confidently support implementation-specific entry points by homestead
Hudson Jameson
@Souptacular
Jan 08 2016 06:04 UTC
@tgerring I agree. Does that mean that that we should stick to whatever implimentation fits the bill for the examples/explanations we are pushing to the guide? IMO, since TurboEthereum is a thing and appears to be maintained, we could just use the Homestead Guide to focus on the Go implimentation since that is what the majority of previous examples is based off of and is usually the reccomended "entry point" software from what I've seen.
Taylor Gerring
@tgerring
Jan 08 2016 06:16 UTC
That's fine by me as long as the guide is not written in a way that would necessarily exclude other implementation examples to be included
i.e. the doucmentation should describe the system genreally whereas the examples can demonstrate the implementation(s)
Hudson Jameson
@Souptacular
Jan 08 2016 06:16 UTC
Sounds good. And as this is collaborative I don't think we should ever not allow PR's that include other implimentation's examples (as long as the need for the example can be justified)
Taylor Gerring
@tgerring
Jan 08 2016 06:17 UTC
Thus, any of the declarative text should be written implementation-agnostic
Hudson Jameson
@Souptacular
Jan 08 2016 06:17 UTC
Good idea. We should stick to that guideline as much as possible.
@zelig I think that the RPC docs belong in the wiki category until a time comes whent here is a clear usage of the new homestead documentation site that is visible. We don't want a repeat of what @frozeman alluded to with the unsuccessful docs.ethereum.org thing. I do agree with you that we want to build a guide strong enough to eventually document all parts of the Ethereum ecosystem in an easy to search and user friendly way, including APIs.
Hudson Jameson
@Souptacular
Jan 08 2016 06:23 UTC
Tomorrow I'll update the GDoc I started with outlines of some of the discussion here to make a clear purpose guide that we can use as our reccomended practices when editing.
Taylor Gerring
@tgerring
Jan 08 2016 06:24 UTC
Thanks for taking the initiative on that @Souptacular. I would like to take a look at what you've got so far, but I don't have VPN set up to circumvent great firewall so I might not get to it until next week
Hudson Jameson
@Souptacular
Jan 08 2016 06:24 UTC
Thanks for including me in all this @tgerring @frozeman and especially @zelig (since he asked for my help initially). I'm enjoying this and look forward to the benefit it provides the community.
@tgerring The link is earlier in the chat a few paragraphs up. No worries, I will likely combine it with the GitHub repo through a PR soon.
Fabian Vogelsteller
@frozeman
Jan 08 2016 09:12 UTC
@zelig i do share most of your vision for the docs as well, but i also leanred in the past that you only get there with a lean startup approach. Meaning: doing one step at a time, and not building the super duper tool wich on the end sits there alone and unused. You first bild a MVP, get a use case and make it useful and then you can make bigger steps.
we are talking here about everybody in the community, which have to be ok with this move, not just you and me. If nobody of them want to move, then you just wasted your time.
Taylor Gerring
@tgerring
Jan 08 2016 09:14 UTC
well, in fairness, we should differentiate the producers and consumers of the content
Fabian Vogelsteller
@frozeman
Jan 08 2016 09:14 UTC
So i would leave the API docs for now out, just link them and use the RTD only for the guide (like tutitoals, and example texts)
Taylor Gerring
@tgerring
Jan 08 2016 09:14 UTC
consumers generally won't care about the way in which the content was assembled
producers will :)
Fabian Vogelsteller
@frozeman
Jan 08 2016 09:15 UTC
as of now the consumers and producer aer alsmost the same. The API is made by developer and read by developers. I look it up myself often
we are very low level here still
Taylor Gerring
@tgerring
Jan 08 2016 09:17 UTC

as of now the consumers and producer aer alsmost the same

not of the homestead documentation, no

Fabian Vogelsteller
@frozeman
Jan 08 2016 09:18 UTC
yes, which is explanations, tutorials and examples, right?
again, the advantage of the wiki pages is, that almost the whole community can go make changes, which happens a lot and is very useful, because this way everybody helps to maintain it.
If you put it in RTD, people would need to sign up, which wont happen juntil they care a lot
Taylor Gerring
@tgerring
Jan 08 2016 09:19 UTC
even though "developers" come in lots of flavors, there's a often wide gap between those that make the API and those that simply want to interact with it. i wouldn't really consider them to be the same
Fabian Vogelsteller
@frozeman
Jan 08 2016 09:20 UTC
sure
Taylor Gerring
@tgerring
Jan 08 2016 09:20 UTC

If you put it in RTD, people would need to sign up, which wont happen juntil they care a lot

not sure about this claim but sign-up just to read would indeed be bad

Fabian Vogelsteller
@frozeman
Jan 08 2016 09:20 UTC
the point is to not make a move, without everybody willing to make it too, because otherwise its a big waste of time and we can definitelty use that time for other things!
Taylor Gerring
@tgerring
Jan 08 2016 09:21 UTC
okay, but "everyone" is not the entire ethereum ecosystem
Fabian Vogelsteller
@frozeman
Jan 08 2016 09:21 UTC
its about beeing efficient
Taylor Gerring
@tgerring
Jan 08 2016 09:21 UTC
in the context of our discussion, "everyone" is only the people writing the documentation
Fabian Vogelsteller
@frozeman
Jan 08 2016 09:22 UTC
no, because we also need people to go to the new places, which is not that easy. Or did you saw yourself use docs.ethereum.org ever?
Taylor Gerring
@tgerring
Jan 08 2016 09:22 UTC
the consumers of the documentation won't care if it's duplicated content, imported from the wiki into a gitbook, or something else... as long as it's useful and accessible
Fabian Vogelsteller
@frozeman
Jan 08 2016 09:22 UTC
i dont want to maintain duplicate content, whats the point?
Taylor Gerring
@tgerring
Jan 08 2016 09:23 UTC

no, because we also need people to go to the new places, which is not that easy. Or did you saw yourself use docs.ethereum.org ever?

sorry, but this is not that big of a problem and has nothing to do with docs site usage as i mentioned earlier

Fabian Vogelsteller
@frozeman
Jan 08 2016 09:23 UTC
for APIs etc you need one place to go to, and not look around, which one is now the most uptodate
Taylor Gerring
@tgerring
Jan 08 2016 09:23 UTC
le sigh
i give up on this hair splitting
Fabian Vogelsteller
@frozeman
Jan 08 2016 09:24 UTC
i dont knwo whats your point, because youre very unspecific. what is it you would like to have?
Taylor Gerring
@tgerring
Jan 08 2016 09:25 UTC
lol, read up
Fabian Vogelsteller
@frozeman
Jan 08 2016 09:25 UTC
btw, just look in the web3.js channel, last messages. there is a guy found a unclear doc and now want to help out improving it. This can happen, because the wiki is very accessible.
Taylor Gerring
@tgerring
Jan 08 2016 09:25 UTC

we are talking here about everybody in the community, which have to be ok with this move, not just you and me

i disagree with this because consumers don't generally care

that's my point
Fabian Vogelsteller
@frozeman
Jan 08 2016 09:26 UTC
maybe, but looking at the last guide. it was barely used from what i saw and heard.
so they did seem to care, because the looked the wiki up and down and read the website
the problem is to scatter informaiton like this.
the wiki itself is not the problem, but the loose structure is and the outdated content.
Taylor Gerring
@tgerring
Jan 08 2016 09:27 UTC
don't you remember my comment that the benefits of writing the guide and discovering gaps in knowledge/functionality outweigh any percieved benefit from it being read?
Fabian Vogelsteller
@frozeman
Jan 08 2016 09:27 UTC
though i agree the RTD are probably better looking
Taylor Gerring
@tgerring
Jan 08 2016 09:27 UTC
it's the same principle that teaching a topic to someone else forces you to understand it better
Fabian Vogelsteller
@frozeman
Jan 08 2016 09:28 UTC
true, but we also need swarm, so when i think about spending 3 weeks on a docs vs getting swarm ready, i would right now prefer the latter :)
Taylor Gerring
@tgerring
Jan 08 2016 09:28 UTC
swarm isn't in scope for homestead
Fabian Vogelsteller
@frozeman
Jan 08 2016 09:29 UTC
because its important for my tools and a lot of peoples dapps
Taylor Gerring
@tgerring
Jan 08 2016 09:29 UTC
remember, we're only talking about a homestead guide
swarm can be added to it later when it is more complete/ready
the immediate goal, it seems, is to have something for a "i'm new to ethereum and want to start developing. what should i know?"
someone asking that question does not care about how the content was assembled
Fabian Vogelsteller
@frozeman
Jan 08 2016 09:31 UTC

yes, we did this 3 times now. The wiki was the first try (which now many outdated exmaple pages), the website the second, and the frontier guide the third.

we should take some learnings from these failed attemts to bring a good guide to life. How can we make it better, more used and helpful this time?

or are we just repeating the frontier guide on another platform now?
why the not just updationg the frontier guide?
Taylor Gerring
@tgerring
Jan 08 2016 09:32 UTC
those are legitimate questions that probably should have a pro/con chart assmbled with the other options
but trying to hand wave and complain about making any change is not a strategy i would encourage
Fabian Vogelsteller
@frozeman
Jan 08 2016 09:33 UTC
what makes RTD now better? the look?
thats what im asking myself. The time we now invest to write something from scratch, has to be justified by the result.
otherwise we can just update the frontier one, which would be far easier
because otherwise this looks for me like “beschäftigungs therapie” (means we create ourself work for no reason)
Fabian Vogelsteller
@frozeman
Jan 08 2016 10:35 UTC

Looking at the main wiki, its quite well organized now.
Not sure about the client wikis.

Whats missing is tutorial like guide. but isnt tha homepage doeing that @alexvandesande then?

Hudson Jameson
@Souptacular
Jan 08 2016 21:59 UTC
The benefits of read the docs are:
  1. More flexibility for formatting than Gitbooks/Markdown
  2. A good search tool
  3. Export options
  4. Community is getting used to and responding well to it based on Solidity switching to it recently as well as Piper Merriam's tools all being there.
I updated the google doc I posted earlier with some guidelines. Let me know what you think.

Documentation Purpose Guidelines:

  • This guide should serve to be an entry level for all Ethereum users and developers.
  • The goal is to create a documentation with information, short tutorials, and examples that will cover all of the basic and intermediate functionality of using Ethereum to interact with DApps or develop a DApp.
  • Any information that is overly specific, technical, or not necessary to accomplish the documentation goal will remain on the Github Wiki. It may be referenced in this guide if necessary.
  • Although much of the information will be similar between the Frontier Guide and the Homestead Guide, efforts need to be made to make sure the information ported over is still accurate.
  • This document is client agnostic and examples and tutorials may be based on any client that the author decides to write on, as long as a distinction is made as to what client is being used in the examples/tutorials.
  • Although overly specific and technical documentation will not be included in the first iterations of this guide, community use and popularity of this guide will dictate future decisions to move Github wiki documentation to this format.

Examples of overly specific and technical documentation include:

  • ETHash, CASPER, ABI, RLP, or other technical specs.
  • Full API specs for protocols. Caveat: If an example, information, or tutorial needs to reference API calls for a client or interface in order to fufill it’s example it is acceptable to reference the specific call. Be sure to make a reference where the user can find remaining pieces of the specific documentation that may be on the GitHub Wiki.
Viktor Trón
@zelig
Jan 08 2016 22:53 UTC
@tgerring , i think re swarm @frozeman means i should rather spend my time on swarm than in doc format hacking. agreed.
Hudson Jameson
@Souptacular
Jan 08 2016 23:46 UTC
That seems to be where I come in ;)
As far as my role in this, I feel I can assemble a pretty good guide with community volunteering and limited help from the core devs (with the exception of updates to their respective areas of expertise if the information is wildy outdated). I am happy to take that role, but will have questions every once in a while on scope and timeline etc. I am hoping the purpose guidelines I outlined above can help that process be more clear so there doesn't have to be much more discussion on the guide writing planning part of this.
Also, I already mentioned this to Zelig, but I cannot accept donations or compensation in the form of ether or BTC for this, so this is purely voluntary work. There is a work related issue that is preventing me from even accepting random donations right now, so I am working on that.
work meaning my day job*