Asciidoctor :: Discussion

more documentation gold

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

2 messages Options

mojavelinux

more documentation gold

Administrator

Brandon West of SendGrid recently announced that he has helped the company open source their documentation. In a three part blog series worth its word count in gold, he explains the benefits, how they did it and what makes good documentation.

Why we open sourced our documentation::

http://blog.sendgrid.com/open-source-documentation/

Creating sustainable documentation with Jekyll::

http://blog.sendgrid.com/creating-sustainable-documentation-with-jekyll/

What makes good documentation (cheat codes)::

http://blog.sendgrid.com/cheat-codes-for-good-documentation/

Here are the docs: http://sendgrid.com/docs/

I declare these posts required reading (for myself) ;)

-Dan

Dan Allen | http://google.com/profiles/dan.j.allen

asotobu

Re: more documentation gold

Really amazing links and really useful information. It has made me think in three possible extensions,

* the first one is to provide a way to make references to javadoc by providing a macro called for example javadoc::. Question: can I access to system env. from Asciidoctor files?
* the other one provide a macro to capture an screenshot of a webpage using for example WebDriver. So screens of documentation will be always updated. screen::http://www.google.com
* add a block which can be used to add style to description of a method and its parameter, so in all documentation it looks with the same style.

And this leaves me to another question should we add two new repositories on github, one called asciidoctor-ruby-extensions and asciidoctor-java-extensions so all official extensions can be stored there?

Alex.