search

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

Files in simple-mod-guide-repo.zip don't meet standards #114

Closed ncbaratta closed 4 years ago

ncbaratta commented 4 years ago

In modular-docs/modular-docs-manual/files/simple-mod-guide-repo.zip we should update the files to include the proper filenaming and folder structures required by the new pantheon build tools.

ncbaratta commented 4 years ago

To clarify, the files in the zip are named things like module-a, module-b, assembly-1

Yet the rules are to have proc-,con-,ref, assembly- [FILENAME/TITLE]

The same goes for the text here: https://redhat-documentation.github.io/modular-docs/#a-simple-example-of-a-modular-guide

VladimirSlavik commented 4 years ago

As an aside, it would be very useful to have these files available also here in the repository, so the zip archive could be generated.

vikram-redhat commented 4 years ago

As far as I know this rule is not final yet (https://github.com/redhat-documentation/modular-docs/issues/111#issue-560052066). Second, even when it does get final, the rule is optional. Teams can choose to go with either the file name option OR the attribute option within the files. The zip file is correct as per the last time these rules were changed and made final.

sterobin commented 4 years ago

@ncbaratta , in follow-up to our FCC call this morning, I've assigned this to me. I'll not only tidy this up a bit, but I'm also going to create a PR here to include a real-life FCC-compliant repo design that's one of several options that I present in my mod doc repo course. We just need something more realistic than that basic one there, which really only serves to show how modules and assemblies relate, not necessarily to give an example of a scalable repo design (for example, it's only one single doc, which is not usually the case).

To be clear, what I'll be suggesting isn't a strict repo template by any means, just an FCC-compliant repo example that's similar to what works for many teams today. Every team faces so many factors, and that's why I have the course, to go through the many, many repo options and factors out there, look at about 15 different Red Hat product/project repos, discuss pros and cons, address single-sourcing and FCC considerations, etc.

From there, a whole lot depends on how groups single-source (if applicable), depending on the community, so this repo is either for non-single-sourced teams, OR for the FCC-compliant repo version that teams generate from a single-sourced repo in preparation for Pantheon publishing.

sterobin commented 4 years ago

@ncbaratta This is being addressed in PR #120 . Pinging you there as part of the reviewers.

@VladimirSlavik , regarding making the repo directly available in the repo, I agree and felt the same way. But I realized, now that we're replacing the example with an actual, more realistic repo, it has made it a bit large and not sure if that matters or not. So I've kept it compressed for now. If you or others still feel it should be exposed fully, no prob. Feel free to comment accordingly on that PR.

@vikram-redhat , this PR also reflects the latest file-naming guidance that @emmurphy1 will be merge in a separately PR shortly. So we should be aligned once her and my PRs are merged.

VladimirSlavik commented 4 years ago

@sterobin I don't really care that much, it's really up to you. My reasoning was along these lines:

But that really is just one opinion :)

sterobin commented 4 years ago

Resolved as part of #120 . Closing.