redhat-documentation / modular-docs

Modular Documentation Project provides guidelines and examples for writing technical documentation using a modular framework.
Creative Commons Attribution Share Alike 4.0 International
82 stars 68 forks source link

Resolves issue #114: Update mod doc repo example and instructions #120

Closed sterobin closed 4 years ago

sterobin commented 4 years ago

All, this address issue #114 and also expands the general repo guidance for first-timers, in conjunction with the mod doc repo workshop. Please review and provide any feedback.

Here's the summary of changes and doc preview links:

Summary of changes:

ncbaratta commented 4 years ago

lgtm

sterobin commented 4 years ago

@rkratky Thanks so much! I committed your re-wording suggestion, and replied on the rest.

Regarding the internal reference issue. I've left as is for now because this raises something that I think we need to bring up on the next team call. There are many important internal suggestions and recommendations that we need to make clear, so we either need to add some attributes and then have different build options for community vs. enterprise, or agree that internal references are okay. I'm fine either way. Just a heads-up, however, that in my workings and research on single-sourced team repos, I've not yet found a team who's community project uses or even tolerates modularization and its conventions. There are growing escalations over this among many projects, and I'm involved with the ascii splitter work that is being taken very seriously now by communities. They seem to be looking for any way out of modularization, from what I can see.

Anyway, point is, I just want to make sure the efforts to avoid internal references are even worth it still. If they are, then great. But we need then to have some attributes and dual building options for this guide. Most or all of the internal refs in this PR for example are critical, imo. Same in #121 .

sterobin commented 4 years ago

@rkratky , @emmurphy1 @Preeticp I've updated this PR to take the approach we discussed in today's meeting, which is to add the mod repo example in a separate mod-doc-repo-example branch, which I've just pushed upstream, and then simplify/broaden the mod repo section of the doc and link to that example branch for more info. I've also tweaked that blanket disclaimer that I added to the intro to not refer to internal terminology.

Let me know what you think and I'll move forward.

Preeticp commented 4 years ago

LGTM