📅 Chat: Documentation Contribution Resources (Feb 18th 2021)

[willi84]

Host: Dave Shevitz

Link: meet.google.com/cbd-hcos-ngf organizer: dshevitz@google.com

Invitees robert@ng-girls.org yallen011@gmail.com splaktar@devintent.com michael@hladky.at mikehartington@gmail.com wileymarques@live.com angular@alyssanicoll.com deborahk8992@gmail.com serkan.sipahi.1979@gmail.com flemke.dev@gmail.com

Event link: https://calendar.google.com/event?action=TEMPLATE&tmeid=NThubXZjazhpNDI0NWxpMzBmcWcyODd2YmsgYjRvamFhajlib2E4Y2tkZWp1ZXBzbzI0NGdAZw&tmsrc=b4ojaaj9boa8ckdejuepso244g%40group.calendar.google.com

[Splaktar]

What's the agenda?

Are there some goals for this meeting?

[Splaktar]

@BioPhoton @mhartington @Bitcollage this is happening now.

[mhartington]

@Splaktar will be coming late, on another call

[Splaktar]

@mhartington no problem, we're still here!

[Splaktar]

Meeting Notes

• @aikidave Discussed the general approach to getting developers answers and back to coding ASAP rather than documenting all of the architecture decisions, pros and cons, and theoretical impacts
• Discussed the new "Last reviewed on" feature and how we hope to start using this to identify docs that need to be reviewed for freshness
• Team is looking into making the docs easier to localize
  • removing humor, idioms, abbreviations, etc
• Discussed prioritization
• Discussed a possible set of guides for how to write a guide, API doc, tutorial, etc
• Discussed use case based documentation, i.e. how to write an autocomplete or how to do x in Angular
  • it's great that there are blog posts, but for some well known solutions, it would be great to add that kind of content to the docs
  • Common Pitfalls, this is how you fix it type section. Best practice solutions (instead of Stack Overflow) [@ngfelixl interested in kicking this off]

Goals

• How can the docs team help?
  • Docs Contributors guides
• How are people willing to help? What are people willing to do?
  • Concerns about writing style being rejected, fear that docs team will want to rewrite everything
  • Interest in more time consuming feedback<->edit loop to bring people up to speed rather than just having someone rewrite it.
  • New guides and content
  • Ensuring resources/docs are up to date
  • Adding words to search string indexes for specific docs, just need a short guide on how to do this
  • Writing new Tutorials: itemizing actual steps to take to get somewhere ** easier to implement theses, contact David if you want to get going on one.
  • New docs-infra features
  • add a TL;DR or highlight section at beginning of each new doc section showing you the meat of the content you are about to dive into.
  • Adding icons or tags to denote which type of doc you are in (task based, tutorial, conceptual, API)
  • cross-platform, accessible, localizable SVG-based diagramming tools
  • Want better search and search results

Documentation references

• Angular Documentation Style Guide
• Google Developers Documentation Style Guide
• Inclusive Documentation
• Word List
• LanguageTool for Google Docs, Word, etc
• LanguageTool for VSCode
• LanguageTool is included in WebStorm and other JetBrains IDEs

[Splaktar]

We just wrapped up! Thank you to everyone who attended! We'll dig in and think about the discussions here and then in a few weeks we'll discuss scheduling another meeting (atm planned for sometime in late-March or early-April.

[willi84]

added a task for the tagging guide: https://github.com/AngularCommunity/angular-missions/issues/11

my two samples:

• good documentation structure: https://tailwindcss.com/docs
  • here you have also this components sections
• sample of good tldr: https://workshops.vuevixens.org/workshops/vue/full-day/ch1.html

[willi84]

https://developers.google.com/hangouts/chat/quickstart/apps-script-bot here is a sample of a feedback button from google for docs. maybe we could consider them?