YUI video : « Thinking documentation as code » – my notes

I view a video about the documentation. It was a conference given at a YUI Conf. The topic was documentation for software, especially when you don’t have anyone dedicated to the task. I am dedicated to the documentation process and content at eZ Systems since 3 months.

What did I wrote down my paper (yes, I am old fashioned sometimes) viewing this video ? (It will be the content of the conference filtered by my brain).

« To first order software documentation is like code ».

It means that Documentation is part of your project, and doc lives in your repository.
I really am convinced by this approach, the documentation for tech stuf has to be near the code.

Code is in the repository because :

  • powerful version control
  • collaboration
  • backup
  • distribution

Documentation elsewhere is duplicating the powerful repository. Documentation is plain text.

Code is expensive (and doc is worse) : this will lead to consequences for someone. If you have choice between fix your code and writing doc : fix your code.

Developer Setup Page Wiki : NO ! MORE !
Use instead :

  • VM
  • Composer
  • automtation build

Editing process

Offline editing is the best, because it’s freedom.

User comments

Dont allow user comments on doc pages :

  • they give bad advices (php.net, AngularJS)
  • adding pixels to the doc out of your control is a bad idea

Add pixels/increase your doc size with value.

Replace comments by a link to forums on the topic (reactJS)

Topic of documentation

What ? How ? = code
Why ? = documentation

Code extract in doc

  • -copy/pastable
  •  line numbers

DRY doc = cross references with links, not duplicate content

Exporting doc

Build targets : HTML, ePub, PDF, TROFF

  • exportable
  • readable
  • searchable
  • text

Questions from the audience :

?/ About the user comments

More pixels in the doc = be careful
=> lot of feedback (is it the place ?)
=> not useful (as doc)
=> moderation to make

?/ What about XML ?

Docbook XML was ok before we have the lightweight markup format (Markdown, ie)

?/ What if we have a documentation debt ?

Write documentation as you go, just like covering with unit testing a legacy code

Vidéo : http://www.yuiblog.com/blog/2014/02/28/yuiconf-2013-evan-goer-on-thinking-of-documentation-as-code/
Slides : http://www.slideshare.net/evangoer/yuiconf-2013documentationiscode


Une réflexion sur “YUI video : « Thinking documentation as code » – my notes

Ajouter mes idées

Entrez vos coordonnées ci-dessous ou cliquez sur une icône pour vous connecter:

Logo WordPress.com

Vous commentez à l'aide de votre compte WordPress.com. Déconnexion /  Changer )

Photo Google

Vous commentez à l'aide de votre compte Google. Déconnexion /  Changer )

Image Twitter

Vous commentez à l'aide de votre compte Twitter. Déconnexion /  Changer )

Photo Facebook

Vous commentez à l'aide de votre compte Facebook. Déconnexion /  Changer )

Connexion à %s