Feedback and Questions on the SystemDocs

[hillbicks]

So, I finally had the time to start the translation of the SystemDocs to german and I’ve come across a couple of things that need clarification. I’m almost finished with chapter 2, but I’d like to start the feedback/clarification process already.

• 1.2 Do we need to have apps and programs? I stuck with programs because they’re the same thing to me. I guess you’re referring to programs for android/iOS when you’re saying apps?

• 1.2 “Document processing of any data provided by any program” I have no idea what that means.

• 1.3 should be called the SAFE client, not the maidsafe client. We should provide a consistent nomenclature so we don’t confuse the users

• 1.3 “cross-plattform” → extend with (Windows, Linux, Mac), otherwise they might not know what cross plattform means.

• 1.5 “As there can be multiple Transaction managers coordinating different safecoin transactions at the same time, an unrestricted number of transactions can take place at network speed.” <— what does that mean?

• 2.2 resilience → meaning redundancy, toughness or resistance? I guess resistance?!

• 2.2.2 “The real key pair is created and the public key is signed by the revocation private key and this packet (public key plus signature) is stored on the network as a Vault Identification key type. This Hash is then used as the Vault identity.” <---- Which hash? the hash of the “packet”?

• 2.2.6 “Users do not require to have their account managed, even in a secured manner.” <— No idea what that means.

• 2.2.6 “As the SAFE Network creates safecoins, users may use these to purchase network resources in an anonymous manner. This uses an exchange or purchasing mechanism.” This needs a lot more explanation for a new user to be understood. I had to read it several times to guess the meaning.

These are my questions so far, I’ll add more as a work my way through the document.

PS: Quite a lot of things are explained more than once in different chapters while others are not explained in enough detail and are hard to grasp for a normal user. A good example is the router stuff. I think most of the normal users won’t understand the use case of a STUN server but would understand the sentence: You don’t need to setup port forwarding on your router. It is a weird mixture of over simplification with a lot technical details. I think there should be two documents; one for the normal user and one for the geeks and nerds out there.

[nicklambert]

Excellent work translating into German. This is a significant undertaking and is highly appreciated!

@hillbicks

1.2 Do we need to have apps and programs?

Not necessarily, an app is a program. We use apps because they are most commonly referred to on mobile devices.

@hillbicks

1.2 “Document processing of any data provided by any program” I have no idea what that means

Yes this is confusing, I will just take this out as we have the catch all in the last bullet “Any existing service that runs on the Internet”

@hillbicks

1.3 should be called the SAFE client, not the maidsafe client.

You are correct, thanks for the heads up, I’ll make this change.

@hillbicks

1.3 “cross-plattform” -> extend with (Windows, Linux, Mac), otherwise they might not know what cross plattform means.

Yes we could be more specific here as something cross platform may not neccessarily run on all platforms. I will also include Android in the list and hopefully IOS soon.

@hillbicks

1.5 “As there can be multiple Transaction managers coordinating different safecoin transactions at the same time, an unrestricted number of transactions can take place at network speed.” <— what does that mean?

Some nodes will be transaction managers for multiple close groups at one time. This ability to multi task will enable transactions to be confirmed as fast the close groups resources (processing/bandwidth…etc…) will allow. Pretty much instantaneously. The number of transactions will not be limited to 7 per second as per bitcoin.

@hillbicks

2.2 resilience -> meaning redundancy, toughness or resistance? I guess resistance?!

No I would say resilience or robustness are more appropriate.

@hillbicks

2.2.2 “The real key pair is created and the public key is signed by the revocation private key and this packet (public key plus signature) is stored on the network as a Vault Identification key type. This Hash is then used as the Vault identity.” <---- Which hash? the hash of the “packet”?

Yes, you are correct, the hash of the packet

@hillbicks

2.2.6 “Users do not require to have their account managed, even in a secured manner.” <— No idea what that means.

There is no third party or administrator maintaining a users account. This is managed entirely between the user and the network.

@hillbicks

2.2.6 “As the SAFE Network creates safecoins, users may use these to purchase network resources in an anonymous manner. This uses an exchange or purchasing mechanism.” This needs a lot more explanation for a new user to be understood. I had to read it several times to guess the meaning.

This is explained more in section 2.5. Please have a read and let me know if this clears things up. I feel that parts of the network are complex and we have to help educate new users by leaving bread crumbs and slowly leading them into high level concepts first, rather than hitting them with everything in one go.

@hillbicks

These are my questions so far, I’ll add more as a work my way through the document.

Great, this really is much appreciated.

@hillbicks

PS: Quite a lot of things are explained more than once in different chapters while others are not explained in enough detail and are hard to grasp for a normal user. A good example is the router stuff. I think most of the normal users won’t understand the use case of a STUN server but would understand the sentence: You don’t need to setup port forwarding on your router. It is a weird mixture of over simplification with a lot technical details. I think there should be two documents; one for the normal user and one for the geeks and nerds out there.

Yes this is a tough task and we have not always got it right. The system docs are intended to be a half way house between the technical papers and the lighter reading on the main website. My feeling is that once the network is launched, only the technical will really want to look at the engine and find out how the network functions. The ‘normal’ users will be more concerned with the UI level side of things and this will be explained on the new website we are working on, using a mix of text and videos.

[jm5]

Hi, is anyone translating to French yet?

[hillbicks]

There was a thread here a while ago about translating the documentation, but as far as I know this is the first translation of the SystemDocs.

I’ll open up a new thread in a bit where we can organize the different translations and keep the information updated in the first post so people know what work has been done already. This way we can use this thread about questions and feedback for the SystemDocs.

I guess you would be willing to translate to french?

[nicklambert]

Yes I think it was just the Examples project that has been translated to French as well as a few other languages.

I agree, creating a dedicated thread to documentation translations is the way to go. I’m working on something right now, but will action the discussed changes highlighted in this thread to the system docs later today.

[happybeing]

When I click on English, German, French etc I get a contents list with page title “Page Not Found”. Is the any content here?

[hillbicks]

I for one haven’t submitted anything as of yet, the translations are just on my laptop right now because I’d like to have someone review my translation before publishing it.

Where are you looking though, because I don’t see the possibility to change the language in the gitbook.

[jm5]

@hillbicks, yes, I would be willing, it would be a good exercise for reviewing the information. Another thread to discuss all this would would be great. I think @happybeing is referring to the link @nicklambert put up. I also get “page not found” when I click on the languages link.

[hillbicks]

Ah, right. Didn’t see the link before. I just looked at the english examples and I don’t think it makes sense to translate anything in there since the information is between 6 and 9 months old. If these are up to date, let us know @nicklambert. My understanding from talking to David about this last year that the SystemDocs are the ones that are update to date.

Btw. I just saw in the dev update that Paige is working on a new website. The offer to translate is of course also valid for the new site, just so you know.

if testnet3 launches in the next couple of weeks I think it would be nice to present it in different languages to reach an even broader audience.

[nicklambert]

I can’t recreate the 404 error. I’ve cleared cache and find all languages to be working, can you please check and try again? Copying in @Viv so he is aware.

The information in the examples project is still relevant as far as I’m aware and we will start to add to this project as the roll out of the network progresses.

The offer of also translating the new website(s) is a great help and once we have finalised the content we would love to get you involved. I agree that getting the network to a broader audience can only be a good thing! Thanks again!

[hillbicks]

Seems to be a server issue, had to try two times to get it working. The german translation is already there, I totally forgot that I already did that. But it’s not that much content anyway, let us know if you plan to update it.

[digipl]

I find the error, is a misplaced backslash.

For example, in spanish:

http://maidsafe.net/maidsafe-examples/es\index.html

must be

http://maidsafe.net/maidsafe-examples/es/index.html

[happybeing]

The error is still there and is because the English, Francais etc links contain a backslash path separator. Changing this to a slash seems to fix:

Broken: http://maidsafe.net/maidsafe-examples/en\index.html
Works: http://maidsafe.net/maidsafe-examples/en/index.html

[Viv]

Hey Guys,

Cheers for letting us know about the backslash issue. It was a bug we had a workaround for from an older version of gitbook and we seem to have missed it when updating to the latest version of gitbook.

It should now be resolved if you force refresh the index page.

<div class="book-langs-index">
    <div class="inner">
        <h3>Choose a language</h3>    
        <ul class="languages">            
            <li>
                <a href="./en/index.html">English</a>
            </li>            
            <li>
                <a href="./de/index.html">Deutsch</a>
            </li>            
            <li>
                <a href="./fr/index.html">Français</a>
            </li>            
            <li>
                <a href="./es/index.html">Español</a>
            </li>            
            <li>
                <a href="./tr/index.html">Türkçe</a>
            </li>            
        </ul>
    </div>
</div>

[hillbicks]

2.2.6

• This is used to manage network authority in addition to the authority a Vault has in relation to its closeness to an address.
  2.6
• Owner can (previous and current owners considered as approved themselves) update all fields. <---- considered as approved themselves? and what fields?
• Pmid manager <—what is that? first time I see that manager mentioned.

2.2.7

• A Vault’s distance from an address is a measure of that Vaults authority to make decisions on that address in a particular circumstance. -< what is an address in this context? ip address?
• In terms of security, network churn prevents attacks as the point of access is constantly moving.<—

2.7.1

• Mentions bootstrap for the first time. We need to explain what is meant by that.

2.7.4

• send the data on named with the requesting key <—on named

3.2

• End Users who are not Farmers, Core Developers or App Builders will need to acquire safecoin from decentralised exchanges. <— this is not really true, is it? Maybe in this strict context, but I think this will confuse new users.

4.1.1

• There are a lot of links after the network_viewer section that won’t show up in the actual gitbook. The syntax for those is wrong. Are they supposed to be there?

4.1.2.

• types.h is listed twice, is that correct?

4.1.5

• additional space for link of self encryption

Also, there a couple of chapters missing from the SUMMARY.md file, I
already updated the file to the best of my knowledge, please check them
when I create the pull request.

[digipl]

[quote=“hillbicks, post:15, topic:3137”]

• This is used to manage network authority in addition to the authority a Vault has in relation to its closeness to an address.
  [/quote] The authority associate to the rank of a Vault is not absolute, but relative to the rest of near Vaults, with which form a group

[quote=“hillbicks, post:15, topic:3137”]

• Owner can (previous and current owners considered as approved themselves) update all fields. <---- considered as approved themselves? and what fields?
  [/quote] Previously, the current owner sign the transfer with the private key so they not need more approbation, and the fields is the owner and previous owner of a safecoin.

[quote=“hillbicks, post:15, topic:3137”]

• Pmid manager <—what is that? first time I see that manager mentioned.
  [/quote] Manage the Pmid client. Both are responsible for the safecoin. See vault library.

[quote=“hillbicks, post:15, topic:3137”]

• A Vault’s distance from an address is a measure of that Vaults authority to make decisions on that address in a particular circumstance. -< what is an address in this context? ip address?
  [/quote] XOR address.

[quote=“hillbicks, post:15, topic:3137”]

• In terms of security, network churn prevents attacks as the point of access is constantly moving.<—
  [/quote] To attack a concrete point you need to surround it with bad nodes but, as the network change constantly, (this is the network churn) made the attack more difficult.

[digipl]

@digipl

Manage the Pmid client. Both are responsible for the safecoin. See vault library.

Sorry, a mistake. The responsible of the safecoin is the Pmid manager.

From white paper:

This special safecoin data is being distributed by the DataManager and
held in PmidManager’s memory (shall never be stored to PmidNode as a
chunk)

[dmitry_n]

Hi,

At no point do any of the other Vaults know anything about the data they have been asked to store other than anonymous network address information.

Does this mean that the Vault knows nothing about the data it’s been asked except anonymous network address information? And how to understand ‘anonymous’ here? Is it encrypted? So that the user who is the owner of this Vault is able to see that there is some network address info but he can’t look through it, right?

And BTW:

Each user of the SAFE Network provides a small part of their computer resources; hard-drive storage, CPU power, and bandwidth.

Is here a typo: semicolon instead of colon?

[digipl]

[quote=“dmitry_n, post:18, topic:3137”]
Does this mean that the Vault knows nothing about the data it’s been asked except anonymous network address information?
[/quote] Yes. The Data Manager ask for a chunk by a number. This number is own Hash512 contents.

[quote=“dmitry_n, post:18, topic:3137”]
And how to understand ‘anonymous’ here? Is it encrypted?
[/quote]Encrypted and obfuscated by the Self Encryption.

[quote=“dmitry_n, post:18, topic:3137”]
So that the user who is the owner of this Vault is able to see that there is some network address info but he can’t look through it, right?
[/quote] The owner really do not see anything except garbage. The vault see chunks of encrypted data.

[nicklambert]

Yes you are correct, this should be a colon. Correction made, thanks!