Base Template - draft #3

[viraji]

ALL Pull-Requests require an associated Issue as documented in How to contribute.

Purpose / why

This PR is based on review comments of #14.

What changes were made?

Changes to :

• base-template.md
• about-base-template.md

Verification

Please help - I have tried to incorporate all review comments to PR #14 as best as I could. But I feel that we can revise and improve further on the " essential elements of your template" section - your suggestions/comments are much appreciated.

---

Checklist

Pull-request reviewer should ensure the following

• Are issues linked correctly?
• Is this PR labeled correctly?
• If template updates: do they align with developers.google.com/style/?
• Did the PR receive at least one 👍 and no 👎 from core-maintainers?
• On merging, did you complete the merge using keywords?
• On merging, did you add any applicable notes to a draft release and link to this PR?

[viraji]

This PR consists of review comments from and improvements to #14.

[barbaricyawps]

Question: I need some more context for this template in order to do a full review. Since the only link you've included is to a prior PR (not an issue) or other conversations, I'm missing some context (and that's probably on me). Btw, is this the issue you're technically trying to resolve with this PR? thegooddocsproject/templates#94

Is this template intended to be primarily used by GDP contributors who are creating a new template? So, for example, the use case is that a GDP contributor who wants to submit a new template will pull your template and use it as their base draft?

And then is the secondary audience an open source project that wants to just provide a base template for a new future templates that includes the core "wrapper" content that it should contain?

If I can get some more context here, I'll jump in and do a more directed review. Thanks!

[camerons]

I feel that @viraji has made improvements to the base templates as it stands, and as such we, should accept this pull request onto the main branch (of our incubator repository). I'll give a day or two for others to comment, and if there are no objections, I will merge. (Feel free to nudge me if I forget.)

I have a lot more thoughts on how I think we can improve the base template. And it will probably be easiest if I provide this feedback in my own I separate pull request, which I can do after accepting @viraji 's pull request.

Answering @barbaricyawps, the target audience for the base template is a template author.

This is confusing to get our heads around:

• The base template needs to explain:
  • How a template author should write writing instructions for:
    • The end doc author.

Both the about-base-template.md and base-template.md should be templates themselves which are forked to create a base-xxx-template.md and xxx-template.md. I feel these documents should have embedded writing instructions inside them. Something like:

{This section is optional. If included, it should cover the provide the following guidance ...}

I'm moving toward the idea that we maybe need three documents:

• Two templates: about-base-template.md and base-template.md
• And one how-to-fill-out-these-docs.md

[aidanatwork]

I think this is a good start. I have a lot of suggestions for how we might be able to potentially change the copy here, but I think that would be done best as new issues or PRs raised on the files once they are merged into the Incubator. I think we should go ahead and merge this PR and then discuss further.

[viraji]

Thank you all for your reviews, feedback and suggestions. @alyssa, sorry I should've been clearer about the task in the PR description, but I see that @cameron Shorter <[email protected]> has already answered your question. Thanks @cameron Shorter <[email protected]> for your suggestion, let's merge this and work on further improvements. /Viraji.

…

On Mon, Dec 14, 2020 at 9:09 AM Aidan Doherty ***@***.***> wrote: I think this is a good start. I have a lot of suggestions for how we might be able to potentially change the copy here, but I think that would be done best as new issues or PRs raised on the files once they are merged into the Incubator. I think we should go ahead and merge this PR and then discuss further. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#17 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AGK37RU7PRH63UBULVUUPPLSUWCGDANCNFSM4UYQMDWA> .

[camerons]

I've merged based on my prior comments. This is a good start to base templates from which we can build within the incubator repository.