Document all phases' high-level functions in app/phases/*/doc.go

[luxas]

Right now this text is missing in most places, or out of date.
The counterproposal here would to NOT document the high-level function of the phase in the code at all, instead in other docs.
cc @fabriziopandini @xiangpengzhao WDYT?

[xiangpengzhao]

From my perspective, it'd be good to document them in other docs which are user-faced. But if the docs in the code can be automatically generated to a user-faced doc, it'd be better to keep the docs in the code for it's easier to keep docs in code up-to-date.

[luxas]

if the docs in the code can be automatically generated to a user-faced doc

I'm not sure how easy/hard this is... @fabriziopandini ?

[fabriziopandini]

IMO high level description of phases should be done in user-facing documents like e.g. init workflow.

I don't think that we should create a direct connection between doc.go files and the above user facing docs. Instead we should use doc.go for documenting implementation details only for packages that need large amounts of introductory documentation as suggested by godoc guidelines.

One last consideration; if we can transform this issue in a checklist with detailed actions items it will be easier to get help from other contributors here

[luxas]

I don't think that we should create a direct connection between doc.go files and the above user facing docs. Instead we should use doc.go for documenting implementation details only for packages that need large amounts of introductory documentation as suggested by godoc guidelines.

👍

if we can transform this issue in a checklist with detailed actions items it will be easier to get help from other contributors here

Sounds good to me, @fabriziopandini can you post such a list with what you see as necessary advice here please?

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[neolit123]

/lifecycle frozen

[timothysc]

Closing this issue in favor of the 1/2 dozen others around promoting phases and current ongoing efforts.