879285 - Decide on document workflow for releng docs

Status: RESOLVED WONTFIX

(Release Engineering :: General, defect)

Description

[John Hopkins (:jhopkins)]

The vcs2vcs documentation is in Hal's user area in people.m.o at the moment which prevents others from contributing.  Let's move these docs to a wiki.

 https://people.mozilla.com/~hwine/tmp/vcs2vcs/

Comment 1

[Chris Cooper [:coop] (he/him)]

Where are Aki's docs for the new system? Maybe this is WONTFIX?

Comment 2

[John Hopkins (:jhopkins)]

Aki's docs are here: https://wiki.mozilla.org/ReleaseEngineering/VCSSync/HowTo

(related note: our TCW docs need to be moved to a wiki http://people.mozilla.org/~hwine/tmp/TCW_docs/)

Comment 3

[Hal Wine [:hwine] use NI!]

morphing bug per comments.

There are several issues here:
 a) where do we put docs that are development
 b) how do we allow the team to mofify such docs
 c) when do we we declare docs "done enough" for a permanent wikimo home
 d) how do we transition docs to IT's mana when we hand over control of the app

There is no general agreement on our documentation life cycle yet - we made some progress at last work week, but nothing since.

For the original purpose of this bug, (b), that was addressed by auto publishing updates from the docs, and I just forgot to close this bug.

It appears it is morphing into "let's decide on a single workflow for docs". I agree that's needed. Let me take this and drive towards consensus.

Comment 4

[John Hopkins (:jhopkins)]

a) I suggest we put documentation into its final resting place immediately whenever possible.  We can add a standard wiki header that states the documentation is in development.
b) "how to modify" is a non-issue if we do the above
c) Once the documentation has got general consensus, we remove the "in development" wiki header.
d) I don't have an answer for this, but we need to consider that mana is inaccessible by the community and as such, removing docs from wiki.m.o in order to populate mana seems undesirable.

Comment 5

[Pete Moore [:pmoore][:pete]]

Totally agree with John.

I think this will simplify doc search, increase transparency, encourage documenting tools (hurdle of deciding a location is obviated), and help establish gaps.

Regarding our workweek discussion: do we have a tracking bug for the missing docs?

Comment 6

[Hal Wine [:hwine] use NI!]

My bad -- the general concept was agreed to in Boston, and I am not proposing changing that or opening the discussion back up.

My questions in comment 3 were intended to be read as "how are we going to implement these things we agreed to" -- i.e. the specific implementation details. To give a flavor:

(In reply to Hal Wine [:hwine] (use needinfo) from comment #3)
> morphing bug per comments.
> 
> There are several issues here:
>  a) where do we put docs that are development
     - SHOULD put in wiki.m.o or relengdocs repository
     - MUST put link to docs in relengdocs if not in one of those locations

>  b) how do we allow the team to mofify such docs
     - for wiki.m.o -- solved problem
     - for relengdocs, clone/commit to github:mozilla/build-relengdocs
     - for relengdocs, now visible on http://docs.pub.build.mozilla.org/ bug 979367

>  c) when do we we declare docs "done enough" for a permanent wikimo home
     - no later than hand off to team support, unless agreement to contrary

>  d) how do we transition docs to IT's mana when we hand over control of the
> app
     - If the "run book" docs live in relengdocs, we can provide all kinds of output to IT (or they can convert themselves).
     - NB "run book" docs are all we're talking about here, since we've yet to transition an app to the MOC, we don't know much beyond this at the moment.

Comment 7

[Hal Wine [:hwine] use NI!]

time has passed this by