CodeNewbie Community

Cover image for [On-Demand Talk] Docs Are Everyone's Business
\alexandrammr
\alexandrammr

Posted on

[On-Demand Talk] Docs Are Everyone's Business

About this talk

In this talk, we'll be covering the then and now journey of how our internal cloud product docs evolved, how the community and customers contribute to these changes and how you can do it too.

Our goal was to make it easy for our teams and customers to use and love our cloud product internally, with the help of documentation. We acknowledged that not all teams and companies look at documentation in an open source way, even internally to their company. This talk is for anyone working on a product that requires documentation, from engineers, marketers, technical writers, content strategist, anyone in the audience should be able to take something useful away.

Takeaways

  1. Open sourcing product documentation internally
  2. Upgrading product documentation both strategically, practically and from a measurement and feedback perspective.
  3. Three things you can do today to make your application a little more accessible

Resources Mentioned

Slides

>> Click here to download slides

🌈 Comment below and ask me questions — I might just answer them during my live speaker discussion!


About Alex Radu

Best known as lover of unicorns and all things magical, including data, design and code, Alex has been working at JPMC since 2016 and is now VP Product Adoption Lead for Public Cloud. She has just finished her MSc Computer Science at the University of Bath and in her work she combines content, data, communities and cloud. Personally, she is currently recovering from a crush on 80s music and glassblowing!


This on-demand talk is part of CodeLand 2021 — a virtual conference brought to you by CodeNewbie & DEV on September 23 & 24, 2021.

Discussion (22)

Collapse
michaeltharrington profile image
Michael Tharrington (he/him)

Heyo! If you have any questions for Alex (@alexandrammr ) please drop them here! 🙏

We're gathering up these questions for the live speaker discussion coming up later on. 📣

Collapse
rainydevbs profile image
Ben Shuck

Thanks for the talk! I was noted for "liking documentation" when I took a task to relocate our docs to a more convenient place. I wasn't sure how to take that, as I thought everyone should like documentation! Writing it down is a great way of retaining and transfering information. I've seen a case myself where poor documentation of an issue caused fixes to be removed and replaced later when the defect re-appeared.

Did the switch from Angular -> React improve the documentation experience? Was this response based on other factors as well?

Collapse
alexandrammr profile image
\alexandrammr Author

Hey Ben, adding a short answer here, I know we covered it on the panel, in short yes and no, it allowed us to do some interactive components and improve the user experience, but from a contributor perspective not really. The other consideration was that we had React devs that could help develop and maintain as opposed to not having Angular experts anymore, so that swayed our decision too, that's not to say we don't have love for Angular anymore!

Collapse
rainydevbs profile image
Ben Shuck

Thanks for the response! It was exciting to have my question be asked while watching. Using the already existing skillset seems to be the theme to some of the discussion throughout Codeland. I fall into that pitfall where I want to branch out with a new idea with a new technology, and it just doesn't mesh well. Capitalizing on the experience already there is the clear answer!

Collapse
callumreid profile image
callumreid

In this transition, did you keep a copy of the old docs available or just replace it in situ? I feel like even poorly written docs being removed might bother some people who had been using them long enough to decode what was in them

Collapse
alexandrammr profile image
\alexandrammr Author

Hey @callumreid I know we answered it live, but I'll leave a short summary here too, we did keep an archive of the old pages while we were redoing all of them, and used analytics to see what the usage was of the old pages. Once we knew they were not being used, we also announced their deprecation and removed them from the customer facing portal and made sure the new pages had all the information up to date, hope this helps!

Collapse
callumreid profile image
callumreid

That is such a sensible solution, thank you!

Collapse
austinxduong profile image
austinxduong

Hello Alex! I'm obsessed with pastel colors on your slides *taking notes 😮

Collapse
alexandrammr profile image
\alexandrammr Author

Pastels are life, it kinda goes with the emoji colors on CodeNewbie and CodeLand badge color pallette 😅

Collapse
noviicee profile image
Novice

Docs are underrated!
They help a new-comer know the project more and in a correct way. Documents should always be clear, concise, and updated.
This talk is really amazing. Thanks Alex!

Collapse
alexandrammr profile image
\alexandrammr Author

Thanks for coming and I totally agree, they are also a great way to bring people in and on board!

Collapse
noviicee profile image
Novice

True! :D

Collapse
srivera12 profile image
Sarah Rivera

Thank you, this was great!

Collapse
alexandrammr profile image
\alexandrammr Author

Thank you for joining, glad you found it useful!

Collapse
fizzybuzzybeezy profile image
fizzybuzzybeezy

Love the idea of open sourcing the docs. Thanks Alex for the look inside your process.

Collapse
alexandrammr profile image
\alexandrammr Author

My pleasure, I just want to spread the docs love!

Collapse
debrakayelliott profile image
Debra-Kaye Elliott

Documentation is so important. I never understood how much, but learning everyday how key it is.

Collapse
alexandrammr profile image
\alexandrammr Author

Yep, if you can't explain what you do in writing or leave them behind for other to learn then you're creating more work for you or someone else out there! Thank you for joining ❤

Collapse
debrakayelliott profile image
Debra-Kaye Elliott

Thanks for your presentation and insight!

Collapse
stephback profile image
Stephanie Back

Are there resources to learn best practices when creating docs?

Collapse
stephback profile image
Stephanie Back

Thanks Alex! I completely missed your resources section initially but your explanation was perfect. Thanks again!

Collapse
alexandrammr profile image
\alexandrammr Author

No worries at all, if you ever get stuck on anything feel free to DM me on Twitter or LinkedIn and we can look at it together if you need help ☺