![Cover image for [On-Demand Talk] Docs Are Everyone's Business](https://community.codenewbie.org/images/wVD_fm_ZTtIvjG1XYqcRAO75B-98P8iT-_waPr1HQIE/rs:fill:1000:420/g:sm/mb:500000/ar:1/aHR0cHM6Ly9jb21t/dW5pdHkuY29kZW5l/d2JpZS5vcmcvcmVt/b3RlaW1hZ2VzL3Vw/bG9hZHMvYXJ0aWNs/ZXMvcnpoNzZzdTVw/dWFxeGszOHQ3OHku/cG5n)
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
- Open sourcing product documentation internally
- Upgrading product documentation both strategically, practically and from a measurement and feedback perspective.
- 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.
Top comments (22)
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. 📣
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
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!
That is such a sensible solution, thank you!
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?
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!
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!
Hello Alex! I'm obsessed with pastel colors on your slides *taking notes 😮
Pastels are life, it kinda goes with the emoji colors on CodeNewbie and CodeLand badge color pallette 😅
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!
Thanks for coming and I totally agree, they are also a great way to bring people in and on board!
True! :D
Love the idea of open sourcing the docs. Thanks Alex for the look inside your process.
My pleasure, I just want to spread the docs love!
Are there resources to learn best practices when creating docs?
Documentation is so important. I never understood how much, but learning everyday how key it is.
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 ❤
Thanks for your presentation and insight!
Thank you, this was great!
Thank you for joining, glad you found it useful!
Thanks Alex! I completely missed your resources section initially but your explanation was perfect. Thanks again!
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 ☺