Improve the guide structure

redhat-documentation / community-collaboration-guide

A Red Hat guide to assist enterprise projects in collaborating with upstream communities on documentation.

https://redhat-documentation.github.io/community-collaboration-guide/

Creative Commons Attribution Share Alike 4.0 International

17 stars 20 forks source link

Improve the guide structure #50

Closed pmkovar closed 7 years ago

pmkovar commented 7 years ago

There were a few structural issues that I addressed with #49, but a few more are remaining. The ToC should follow a standard workflow used by a typical upstream documentation project.

Decide on the structure (+ create repos if needed)
Migrate content if applicable
Update
Render locally and/or build
Publish
Sync with downstream

Let's change the guide structure to reflect that. @nengard Thoughts?

ncbaratta commented 7 years ago

Yes, I agree! I was trying to get at this in our last meeting by starting small with moving a few things around. But, you are missing a few other steps. There is the step of deciding if you can even work with the community at all. And then there are the tips for working with a community and communication guidelines and such. Should we maybe have two different guides? One for the practical and one for the planning?

Let's talk about this next week on our meeting, I bet the entire team has some great ideas as well.

I have added this to the agenda.

pmkovar commented 7 years ago

But, you are missing a few other steps. There is the step of deciding if you can even work with the community at all. And then there are the tips for working with a community and communication guidelines and such.

Good point. This wasn't supposed to be a definite list or a complete ToC. Deciding if you can even work with the community should probably precede all the other steps. Tips etc. could live in an appendix, if we want to (visually) separate it from the workflow steps?

ncbaratta commented 7 years ago

Sounds great to me! So maybe:

Introduction
Evaluating Community
Communicating with Community
Decide on the structure (+ create repos if needed)
Migrate content if applicable
Update
Render locally and/or build
Publish
Sync with downstream
Tips & Tricks for working with communities

pmkovar commented 7 years ago

LGTM, thanks.

ncbaratta commented 7 years ago

Replace Communicating with Collaborating - and move this above evaluating.

ncbaratta commented 7 years ago

This is done for the chapters we have content in - comments added as placeholders for chapters we don't have yet.