Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Writing Decent Documentation, a learning journey with plenty of pitfalls Abdel Dadouche DJZ Consulting adadouche@hotmail.c...
Me? Abdel Dadouche Freelance Consultant • Last Permanent Job: SAP Developer Relation (2016-2019) ▫ Published 100+ tutorial...
First, do you remember these? (if you are old enough) (they are books made of paper…)
What we expect from documentation & the reality...
Applicable to NOT only documentation
Who is going to need / read it? What will it be used it for? Identify the Personas ▫ Business Users ▫ Sys Admins ▫ Develop...
The Pitfalls to avoid before starting
The Art of Technical Writing
What is a technical writer ? A professional information communicator whose task is to transfer information between two or ...
So, who should provide content for your documentation? There is many people in your organization who can provide valuable ...
Key Formats: How-to, tutorials, feature & reference guides… • Feature guide ▫ Use it to explain a concept using a context ...
While reading, writing and sharing content
• Think that documentation is “optional” • Think that quality is “optional” • Think that “one” documentation can fit every...
Food for thought… The Must-Do Make your personas, levels and goals very visible / explicit in your documentation Collect s...
DevRel Salon - Writing Decent Documentation, a learning journey with plenty of pitfalls
DevRel Salon - Writing Decent Documentation, a learning journey with plenty of pitfalls
Upcoming SlideShare
Loading in …5
×

DevRel Salon - Writing Decent Documentation, a learning journey with plenty of pitfalls

132 views

Published on

The January 2020 DevRel Salon topic was around "documentation" where I was asked to share my experience.
This talk try to transcribe some of the key learnings over 20 years as a support engineer, and developer (somehow), a consultant, an architect and last but not least as a Developer Advocate at SAP.

Published in: Technology
no profile picture user

  • Be the first to comment

  • Be the first to like this

DevRel Salon - Writing Decent Documentation, a learning journey with plenty of pitfalls

  1. 1. Writing Decent Documentation, a learning journey with plenty of pitfalls Abdel Dadouche DJZ Consulting adadouche@hotmail.com @adadouche
  2. 2. Me? Abdel Dadouche Freelance Consultant • Last Permanent Job: SAP Developer Relation (2016-2019) ▫ Published 100+ tutorials on developers.sap.com (GitHub), an end to end blog series on SAP HANA, express edition & ML (over +40k views). ▫ Hosted 50+ SAP CodeJam hands on events around Machine Learning with SAP, SAP HANA, SAP Cloud Platform & SAPUI5 with 1k attendees over 3 years ▫ Conference and meetup speaker at GOTO Chicago, QCon New York, SAP TechEd, SAPPHIRE, SAP Inside Tracks (#sitFRA, #sitWRO, #sitWDF, #sitBRU) • Languages: ▫ Java, SQL, JS, Python, Bash Shell & too many other ▫ “Predictive” & “machine learning” • Hobbies: ▫ Hackathon & Home Improvements activities
  3. 3. First, do you remember these? (if you are old enough) (they are books made of paper…)
  4. 4. What we expect from documentation & the reality...
  5. 5. Applicable to NOT only documentation
  6. 6. Who is going to need / read it? What will it be used it for? Identify the Personas ▫ Business Users ▫ Sys Admins ▫ Developers ▫ … Identify their Levels ▫ Beginners (100) ▫ Intermediate (200) ▫ Advanced (300) ▫ Expert (400) ▫ … Keep in mind that It’s not because you want to write about something that someone will need/read it! Identify the Goal ▫ Get Started ▫ Learn ▫ Build ▫ Setup ▫ Configure ▫ Administrate ▫ Troubleshoot ▫ …
  7. 7. The Pitfalls to avoid before starting
  8. 8. The Art of Technical Writing
  9. 9. What is a technical writer ? A professional information communicator whose task is to transfer information between two or more parties, through any medium that best facilitates the transfer and comprehension of the information. (Wikipedia) In many organization they are seen as: The reality is more like: But he can’t do it on its own!!!
  10. 10. So, who should provide content for your documentation? There is many people in your organization who can provide valuable content for your documentation: • Product Marketing • Product Owners • Developers • QA/Test Engineers • Consulting / Professional Services • Advocates & Evangelists (Interns don’t count! )
  11. 11. Key Formats: How-to, tutorials, feature & reference guides… • Feature guide ▫ Use it to explain a concept using a context ▫ Allows comparing approach, use different angles or provide opinions ▫ Avoid detailing instructions or technical details as this should be done in other docs • How-to guide: ▫ Provides a series a steps to achieve a specific goal/task ▫ Assumes basic knowledge and understanding of the solution (no completeness needed) • Reference/Technical guide: ▫ Provide a complete “technical” description of the software ▫ When appropriate, provide examples to illustrate the description ▫ Avoid including concepts or how-to’s • Tutorial: ▫ Should allow anyone to get started quickly ▫ Best suited with an “end to end” concrete scenario where multiple things will be learned I encourage you to check the following blog: https://www.divio.com/blog/documentation/
  12. 12. While reading, writing and sharing content
  13. 13. • Think that documentation is “optional” • Think that quality is “optional” • Think that “one” documentation can fit everyone for everything • Think that “Developers” can do it all on their own! • Think that it [doesn’t take/takes too] much time to deliver it • Think that “Gamification” will save you • Think that you don’t need to define some kind of “style guide” • Think Google is your best friend and you don’t need a search capability • Think that because you want to write about something that someone will need/read it! Common Pitfalls / Excuses for Bad Documentation
  14. 14. Food for thought… The Must-Do Make your personas, levels and goals very visible / explicit in your documentation Collect stats about documentation search & usage to help you understand your readers Setup an SEO strategy to avoid landing on the wrong content (including from your own search engine) My Crazy ideas Why not publish your “Functional Test”, “Unit Test” and “User Stories” as part of your documentation Implement AI/ML to recommend content or help “search” (bot) Allows users to contribute or provide online feedback on your content/samples

×