Create modular docs "quick reference" guide

[annibond]

The modular docs effort in CCS has produced a great guide available here. However, referring to PR#65, there has been a request for a condensed guide for those who are familiar with the concepts behind modular documentation BUT still want a way to reference the info quickly.

I have proposed: https://docs.google.com/document/d/188ysdKU4u5OwdrSj625saltfCnjpyW9yxxoyRUjkQIY/edit

[vikram-redhat]

@annibond - that link says I require permission (I am logged in via my RH account)

[mishaone]

+1 need permission. @annibond could you open it up so we can view the document please?

[tylerkelly13]

I have had a look at this doc. It appears to be a link to the wrong document. @annibond could you double check the link you provided above?

[tylerkelly13]

Correct link?: https://docs.google.com/document/d/1BDQvC3ogAUHeapQIEheokDPb2bXrZJVEt6oecjSwL3U/edit?ts=5b757e01#

[ChristyWatkins]

Ingrid gave us the link to this document because the link above isn't the correct one:

https://docs.google.com/document/d/1BDQvC3ogAUHeapQIEheokDPb2bXrZJVEt6oecjSwL3U/edit?ts=5b757e01#

[annibond]

My apologies. This email got lost in a cluster. Yes this is correct. Double checking the permissions.

…

On Tue, Aug 28, 2018 at 8:20 AM, Tyler Kelly ***@***.***> wrote: Correct link?: https://docs.google.com/document/d/ 1BDQvC3ogAUHeapQIEheokDPb2bXrZJVEt6oecjSwL3U/edit?ts=5b757e01# — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#75 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/Ai25H7Q4QNDOaCfp7E53YiyLYmSwRu0Iks5uVTV1gaJpZM4WEWLz> .

-- Anni Bond Technical Writer | Product Documentation & Support O: 919-754-4349 | M: 919-758-6935 IRC: anbond

[adahms]

@annibond - Reviving this thread from a good long time ago now.

I suspect we'll need to spread the word about this discussion again, but taking a look at what is proposed, it looks like we might be able to take a modular approach (surprise, surprise) and combine some of the existing modules into a separate assembly that is more compact.

@rkratky - your understanding of the github.io hosting mechanism is much better than mine. Would having two assemblies in the same repo cause any issues to the way things are set up?

In the meantime, I'll try and spread the word about having a shorter reference and gather opinions about it to see what support and interest we have today.

[laubai]

This sounds useful to me. I've just started doing some live reviews of the freshly modularised content with my team, I'd be happy to contribute our checklist of things that we're having to verify as part of these reviews, e.g. does ID exactly match the title except for the context suffix, does the file name have module type prefixed and module language suffixed, does the module have an introductory sentence to set context, etc.

[vikram-redhat]

This sounds useful to me. I've just started doing some live reviews of the freshly modularised content with my team, I'd be happy to contribute our checklist of things that we're having to verify as part of these reviews, e.g. does ID exactly match the title except for the context suffix, does the file name have module type prefixed and module language suffixed, does the module have an introductory sentence to set context, etc.

Hey Laura - are these checklists specific to your team? Because they are not mod docs specific, right? (we dropped some of these requirements a while back).

[leswilliams44]

I think a condensed quick reference guide is a great idea!

[JStickler]

What I've done is take the templates and strip all out all explanatory material and then copy/rename them when I'm creating topics. So essentially a "quick reference" for myself, but one that I refer to as I'm creating content. So +1 for "quick reference is useful to me".

[adahms]

Hi everyone - thanks for the feedback!
Based on the comments here and elsewhere, it looks like there is some interest in going ahead with this on some scale. If someone is particularly interested in taking this on, you're welcome to have a go, otherwise I'll set aside some time in the next week or so to have something up for review on GitHub.

[thatdocslady]

The comments here are reading to me like two different requests:

1. Create a review/compliance checklist for migrated or newly authored content: I have a feeling that multiple teams are maintaining their own checklists. For RHOSP we created this list in Confluence: https://docs.jboss.org/display/RHOSPDOC/Mod+Docs+Compliance+Checklist. Maybe we can run some kind of survey to collect these lists and try to create a more generic version as its own topic in the guide.
2. Compile a shorter quickstart-style guide with high-level: This feels like a bigger task because the reference guide is pretty long and from my interaction with it I feel that a lot of the topics need to stay grouped together. That being said, the guide is constructed very much like a reference guide more than a user-story task based guide, which raises the question of do we want to convert it to such a guide or keep it as a reference and write a shorter quickstart as a companion. This probably depends on what CCS as a whole will benefit from in the short term migration as well as long term authoring and maintenance of FCC.

Possibly more questions than answers in this comment but hopefully it contributes something useful :)

[thatdocslady]

Following today's review board discussion, I'm going to attempt to scope out the two points and come up with something actionable :)

[thatdocslady]

Resources survey revealed a strong preference for a quick-reference module with links to procedures and conceptual information. Seeking out any volunteers to help with drafting.