search

internetee / registry

TLD Management Software
Other
45 stars 19 forks source link

Review documentation #247

Open artur-intech opened 7 years ago

artur-intech commented 7 years ago

№ 1: https://github.com/internetee/registry/blob/master/doc/whois.rm

vohmar commented 7 years ago

@artur-beljajev no, these docs need to be updated, not removed

artur-intech commented 7 years ago

Why do we need them?

vohmar commented 7 years ago

it explains how the system works - data models have been a big help in the past. Documentation is good in case things are not self-explanatory.

artur-intech commented 7 years ago

ok, then we probably need to automate this process somehow, since above mentioned docs can get outdated extremely easily (as they are now).

vohmar commented 7 years ago

yes, please do. These schemas were automatically generated by the initial developers

artur-intech commented 7 years ago

I submit removal of № 1, 2, 4. Concerning № 3, they give no benefit, IMHO. They don't explain how the system works, they just provide raw data of database columns and model relationship, which are anyway available by just looking at DB or models directly. Instead of investing time to support docs, I would invest this time in making the code more understandable.

If you still prefer to automate this, I kindly ask to explain the benefits we gain if we do this.

vohmar commented 7 years ago

no1 might be necessary for modular architecture no2 seems necessary as it guides the setup of the autotest environment.
no3 db complete model must be kept updated no4 update as necessary

artur-intech commented 7 years ago 
All registry demo data can be found at:
db/seeds.rb

is also outdated

artur-intech commented 5 years ago

https://github.com/internetee/registry/blob/master/doc/epp-examples.md#epp-domain-with-valid-domain-returns-domain-info

Request: <domain:pw>2fooBAR</domain:pw> Response: <domain:pw>98oiewslkfkd</domain:pw>

Request transfer code is not needed according to https://github.com/internetee/registry/blob/master/doc/epp/domain.md#domain-info, therefore needs to be removed. Otherwise it is confusing example.

vohmar commented 5 years ago

just as a reminder we need to update these documents in addition to other doc existing and mentioned in this ticket (added links to rejected PRs as reference):

there are gems used to update documentation previously. Some of these gems are listed here:

yulgolem commented 4 years ago

2, 4 updated by https://github.com/internetee/registry/pull/1284

yulgolem commented 4 years ago

3 there is no need to store in project, RubyMine generates them on the fly (https://www.jetbrains.com/help/ruby/working-with-diagrams.html#class_diagram).