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.
A Documentation Crash Course …for developers LinuxCon, Berlin
 @chrischinch
What’s one of the first things you look at with a new project?
• W • W • W ho are you writing for? hat are they trying to achieve? hy are you writing this? Youhavehopefullyansweredthese...
Assume nothing
Refine your concept(s)
API docs are (not) always enough
It’s not a manual
Interactivity
Language Selected highlights in (mostly) English, sorry…
Involve the reader
“function takes parameter x and returns value y”
“You can use function to return the value of y based on x”
Passive vs Active
“function can be used to return the number of y based on x”
“Holiday approval will be notified in due course”
Keep it short
“If I Had More Time, I Would Have Written a Shorter Letter” – Pascal, Locke, Franklin, Thoreau, Cicero, Wilson?
Structure
Consistency
Tools In brief…
Format and editing
Management and rendering
Testing, linting and automating
Write your own
Want More? • www.meetup.com/Write-The-Docs- Berlin • slack.writethedocs.org
–Me (maybe) “Documentation isn’t just for developers”
Thank You! Chris Ward contentful.com gregariousmammal.com @chrischinch I have stickers and merchandise!
A Documentation Crash Course, LinuxCon 2016
A Documentation Crash Course, LinuxCon 2016
A Documentation Crash Course, LinuxCon 2016
A Documentation Crash Course, LinuxCon 2016
Upcoming SlideShare
Loading in …5
×

A Documentation Crash Course, LinuxCon 2016

256 views

Published on

How many times have you come across an awesome looking library or tool that you're keen to work with in your own project but can't even begin to understand how to use it?

Programmers are great at creating amazing and cutting-edge code, but not always so good and explaining themselves, and I want to help. In this presentation I want to draw upon my experience in writing tutorials and technical documentation to help you write clear, concise and usable documentation for your own projects.

Published in: Technology
License: CC Attribution License
no profile picture user
  • Simple tips but meaningful. It can really help college applicants to write their personal statement essay. Correspondingly, at HelpWriting.net they assist college applicants write a significant and efficient essays that convey their qualifications and potentials.
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here

  • Be the first to like this

A Documentation Crash Course, LinuxCon 2016

  1. 1. A Documentation Crash Course …for developers LinuxCon, Berlin
 @chrischinch
  2. 2. What’s one of the first things you look at with a new project?
  3. 3. • W • W • W ho are you writing for? hat are they trying to achieve? hy are you writing this? Youhavehopefullyansweredthesebeforedevelopment…
  4. 4. Assume nothing
  5. 5. Refine your concept(s)
  6. 6. API docs are (not) always enough
  7. 7. It’s not a manual
  8. 8. Interactivity
  9. 9. Language Selected highlights in (mostly) English, sorry…
  10. 10. Involve the reader
  11. 11. “function takes parameter x and returns value y”
  12. 12. “You can use function to return the value of y based on x”
  13. 13. Passive vs Active
  14. 14. “function can be used to return the number of y based on x”
  15. 15. “Holiday approval will be notified in due course”
  16. 16. Keep it short
  17. 17. “If I Had More Time, I Would Have Written a Shorter Letter” – Pascal, Locke, Franklin, Thoreau, Cicero, Wilson?
  18. 18. Structure
  19. 19. Consistency
  20. 20. Tools In brief…
  21. 21. Format and editing
  22. 22. Management and rendering
  23. 23. Testing, linting and automating
  24. 24. Write your own
  25. 25. Want More? • www.meetup.com/Write-The-Docs- Berlin • slack.writethedocs.org
  26. 26. –Me (maybe) “Documentation isn’t just for developers”
  27. 27. Thank You! Chris Ward contentful.com gregariousmammal.com @chrischinch I have stickers and merchandise!

×