📅 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: #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