Closed Bug 879285 Opened 9 years ago Closed 6 years ago

Decide on document workflow for releng docs

Categories

(Release Engineering :: General, defect)

x86
All
defect
Not set
normal

Tracking

(Not tracked)

RESOLVED WONTFIX

People

(Reporter: jhopkins, Assigned: hwine)

References

Details

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/
Product: mozilla.org → Release Engineering
Where are Aki's docs for the new system? Maybe this is WONTFIX?
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/)
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.
Assignee: nobody → hwine
Status: NEW → ASSIGNED
Summary: Move vcs2vcs documentation to a wiki → Decide on document workflow for releng docs
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.
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?
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.
Depends on: 979371
time has passed this by
Status: ASSIGNED → RESOLVED
Closed: 6 years ago
QA Contact: mshal
Resolution: --- → WONTFIX
You need to log in before you can comment on or make changes to this bug.