Documentation Improvements #625

gichiba · 2019-05-24T21:53:12Z

This PR tracks all improvements to documentation following the merge of #614

updated instructions for running the reputation miner, including the reputation visualizer
improved 'get started' directions
improved extensions examples
~~an API section (blocked by the lack of a natspec parser)~~ As Ryan pointed out, this was already solved in Generate documentation for interface contracts #622
~~updated network inheritance diagram (which includes domainRoles)~~ this was too detailed so instead I did an architecture level diagram of the network design. The inheritance model is not really that useful on paper, plus it can get very brittle to maintain. Devs would normally go to the codebase to look at details like this.

ryanchristo · 2019-05-25T09:07:57Z

an API section (blocked by the lack of a natspec parser)

This is built using a custom script in #622. The natspec comments in the interface contracts could use some punctuation fixes including the use of back ticks when referring to a _variable but the script is accurately parsing natspec comments without the need for an external natspec parser.

I'd like to propose that this branch remain in existence permanently, and all documentation changes be pushed here.

I think it would be best to keep the standard Gitflow Workflow, merging feature branches such as this into the develop branch and not breaking the pattern by adding an additional permanent branch.

When we are ready to publish changes to documentation, they should be aligned with a new release, therefore we would merge the develop branch into the master branch. If hotfixes need to be made to the documentation, a feature branch can merge those changes directly into master.

When we are ready to merge develop into master for a new release, we would first need to merge master into develop so that the develop branch includes the hotfixes we merged to master. This is a standard workflow that I think we should maintain.

We can then turn off the circleci builds to this branch and save their servers from frivolous flops.

As @elenadimitrova mentioned here in #612, you can skip CircleCI builds by adding [skip ci] to the end of the commit message.

gichiba · 2019-05-27T17:09:40Z

Hmmm, yeah ok that seems to make sense, although I for some reason have doubts that the [skip ci] flag stops all of the builds from running. But I guess that's a very minor point to a much more important practice.

Okay, closing this and will open up a new feature-specific docs branch for the next round.

elenadimitrova · 2019-05-28T05:34:13Z

I am going to reopen this PR for the purposes of updating the points Griffin made in the improvements list above. It won't "remain in existence permanently" and it will be merged around the imminent go-live. The current level of documentation (even with the lovely parsed interface docs) is not sufficient for a developer to be productively using the network. There is a lot of know-how that's just not captured.

elenadimitrova · 2019-05-29T08:57:58Z

docs/CONTRIBUTING.md


-### Test coverage 
+### Documentation-only contributions
+If changes only affect files in the `docs/` directory, suspend CI builds by adding `[skip ci]` or `[ci skip]` to your commit message.


"suspend" it too strong a word here. Maybe "skip"?

elenadimitrova · 2019-05-29T10:44:13Z

docs/_Docs_GetStarted.md

 If you intend to work with `glider-rc.1` on the Görli testnet, proceed with installation below, skipping the "local development and testing" section.


 ### Installation


This section is an almost exact duplicate of the repo readme which is why it goes out of date so often. I'd like to remove it altogether.

I don't want to butcher this section before @gichiba and @ryanchristo agree?

I think this section could be improved upon and trimmed down a bit but I also think it would be best if a developer was able to get started without needing to leave the page (moving from the docs to the readme and back to the docs).

I am going to fight very very hard against any duplication of installation instructions and dependencies. If you want to keep and maintain it here, I will remove it from the readme.

elenadimitrova · 2019-05-29T14:15:09Z

docs/_Docs_Overview.md

 The Colony Network is a large set of contracts that together define how all colonies operate and interact with people and other smart contracts on the Ethereum blockchain.

-Colony is designed to be modular, upgradable, and eternally backwards-compatible. This is achieved through a sophisticated contract architecture that requires a bit of exposition. It is recommended that any developer seeking to understand the Colony Network solidity implementation first read the [Colony White Paper](https://colony.io/whitepaper/), or at the very least, the [White Paper TL;DR](/colonynetwork/whitepaper-tldr-colony/).
+Colony is designed to be modular, upgradable, and eternally backwards-compatible. This is achieved through a sophisticated contract architecture that requires a bit of exposition. It is recommended that any developer seeking to understand the Colony Network solidity implementation first read the [Colony White Paper](https://colony.io/whitepaper.pdf), or at the very least, the [White Paper TL;DR](/colonynetwork/whitepaper-tldr-colony/).


https://github.com/JoinColony/colonyNetwork/pull/625/files#diff-f3b3c6b116ba5f2f1a88aa387b245ae9R58 These contracts have very little to do with the CLNY token :/

elenadimitrova · 2019-05-31T06:14:18Z

docs/_Docs_Overview.md

 Data structures, enums, constants and events are declared in a dedicated `*DataTypes.sol` contract, e.g. `ColonyDataTypes.sol`.

-For clarity all storage variables are held separately in a `*Storage.sol` contract, e.g. `ColonyStorage.sol`. Storage variable declaration ordering is crucial to be maintained correctly as that ordering cannot change during contract upgrages, due to the [contract upgrade mechanism](/colonynetwork/docs-the-delegate-proxy-pattern/) we use.
+For clarity, all storage variables are held separately in a `*Storage.sol` contract, e.g. `ColonyStorage.sol`. Storage variable declaration ordering is crucial to be maintained; network upgrades and recovery depend on a consistent and clear storage layout. All variabes are commented with slot numbers to support developers.


network upgrades and recovery depend on a consistent and clear storage layout
This is insufficient to convey the full meaning.
"ordering cannot change during contract upgrades" <- this is what it's all about. If you insert a new storage variable amongst existing ones for example, it'll break the upgrade even if the storage layout is clear.

gichiba · 2019-06-04T03:47:06Z

docs/_Docs_Permissions.md

+Skill `254` has children: `[]`

-Currently this role grants permission for no functions. It is a placeholder for the dispute resolution system, to be implemented in later releases.
+If a user with "Admininstration" authority in domain `2` wants to finalize a payment in domain `5`, they would call:


I hope you approve of me changing the example function, @elenadimitrova. I think it's a little confusing to make the first example of permissioned functions a function that alters permissions 😛

and into ... well ... permissions section. Also renamed the The Delegate Proxy Pattern page to Upgrade design for clarity [skip ci]

… ci]

…n reputation mining [skip ci]

Ensure Goerli is spelled consistently

… changes[skip ci]

…ip ci]

gichiba added in-progress documentation labels May 24, 2019

gichiba assigned elenadimitrova and gichiba May 24, 2019

gichiba closed this May 27, 2019

elenadimitrova reopened this May 28, 2019

elenadimitrova reviewed May 29, 2019

View reviewed changes

elenadimitrova force-pushed the documentation branch 2 times, most recently from f2419c1 to b6a60fd Compare May 30, 2019 12:40

elenadimitrova reviewed May 31, 2019

View reviewed changes

elenadimitrova force-pushed the documentation branch from 7a20253 to 71daac3 Compare June 3, 2019 17:31

gichiba commented Jun 4, 2019

View reviewed changes

gichiba force-pushed the documentation branch from 94c130b to 988b71e Compare June 4, 2019 03:59

gichiba and others added 12 commits June 5, 2019 20:26

fix typo in welcome doc

0f0ab75

add skip ci not to contribution guidelines

d6440e5

Re-order docs; trim "get started" copy [skip ci]

12f5cbd

Add missing .pdf to the whitepaper link [skip ci]

d7f5c33

Add missing contracts to docs overview [skip ci]

2340b24

Rewrite the Architecture section of the Overview page [skip ci]

dbbd7fe

Move a permissions section away from upgrades section

b20affa

and into ... well ... permissions section. Also renamed the The Delegate Proxy Pattern page to Upgrade design for clarity [skip ci]

Updated wording in Permissions intro page [skip ci]

873a926

minor change to contributing guidelines [skip ci]

d64d733

Copy edits to Overview doc [skip ci]

028d5f4

Small edits in Permissions doc [skip ci]

c677c4f

fix links for changed "upgrade design" page [skip ci]

a38d6d4

elenadimitrova and others added 3 commits June 5, 2019 20:26

Updates to Extensions and Permissions pages

4afc8d9

Remove the Releases docs pages and point to the GitHub releases [skip…

bacf2e5

… ci]

Edit Permissions doc to have a more straightforward example [skip ci]

9959c00

elenadimitrova force-pushed the documentation branch from 988b71e to 9959c00 Compare June 5, 2019 17:27

elenadimitrova and others added 6 commits June 5, 2019 22:42

Updates to the Reputation Mining page in the docs [skip ci]

817e81f

Add information about minimum CLNY stake required for participating i…

4baa688

…n reputation mining [skip ci]

Update readme and make it work better with GetStarted docs page

4ca60d3

Ensure Goerli is spelled consistently

Add details on working with the convenience functions for signed task…

7e777ac

… changes[skip ci]

edit reputationMining, and a few small corrections to get started [sk…

cf3d94a

…ip ci]

small line change in docs [skip ci]

7d9a593

gichiba added ready-for-review and removed in-progress labels Jun 6, 2019

elenadimitrova removed the ready-for-review label Jun 6, 2019

elenadimitrova approved these changes Jun 6, 2019

View reviewed changes

elenadimitrova merged commit 9b15079 into develop Jun 6, 2019

elenadimitrova deleted the documentation branch June 6, 2019 18:34

gichiba mentioned this pull request Jun 7, 2019

🙈 Errata in docs #640

Merged

kronosapiens added this to the Sprint 27 milestone Jun 10, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Documentation Improvements #625

Documentation Improvements #625

Uh oh!

gichiba commented May 24, 2019 •

edited by elenadimitrova

Loading

Uh oh!

ryanchristo commented May 25, 2019 •

edited

Loading

Uh oh!

gichiba commented May 27, 2019

Uh oh!

elenadimitrova commented May 28, 2019

Uh oh!

elenadimitrova May 29, 2019

Uh oh!

elenadimitrova May 29, 2019 •

edited

Loading

Uh oh!

elenadimitrova May 29, 2019

Uh oh!

ryanchristo May 29, 2019

Uh oh!

elenadimitrova May 29, 2019

Uh oh!

elenadimitrova May 29, 2019

Uh oh!

elenadimitrova May 31, 2019

Uh oh!

gichiba Jun 4, 2019

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

		If you intend to work with `glider-rc.1` on the Görli testnet, proceed with installation below, skipping the "local development and testing" section.


		### Installation

Documentation Improvements #625

Documentation Improvements #625

Uh oh!

Conversation

gichiba commented May 24, 2019 • edited by elenadimitrova Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ryanchristo commented May 25, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gichiba commented May 27, 2019

Uh oh!

elenadimitrova commented May 28, 2019

Uh oh!

elenadimitrova May 29, 2019

Choose a reason for hiding this comment

Uh oh!

elenadimitrova May 29, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elenadimitrova May 29, 2019

Choose a reason for hiding this comment

Uh oh!

ryanchristo May 29, 2019

Choose a reason for hiding this comment

Uh oh!

elenadimitrova May 29, 2019

Choose a reason for hiding this comment

Uh oh!

elenadimitrova May 29, 2019

Choose a reason for hiding this comment

Uh oh!

elenadimitrova May 31, 2019

Choose a reason for hiding this comment

Uh oh!

gichiba Jun 4, 2019

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

gichiba commented May 24, 2019 •

edited by elenadimitrova

Loading

ryanchristo commented May 25, 2019 •

edited

Loading

elenadimitrova May 29, 2019 •

edited

Loading