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.

1. Writing Decent Documentation, a learning journey
with plenty of pitfalls
Abdel Dadouche
DJZ Consulting
adadouche@hotmail.com
@adadouche

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

4. First, do you remember these? (if you are old enough)
(they are books made of paper…)

5. What we expect from documentation & the reality...

6. Applicable to NOT only documentation

7. 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
▫ …

8. The Pitfalls to avoid before starting

9. The Art of Technical Writing

10. 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!!!

11. 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! )

12. 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/

13. While reading, writing and sharing content

14. • 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

15. 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