8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

1/47

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

2/47

Who Am I?

Im Loren Segal

I blog: http://gnuu.org

I tweet: @lsegal

I use Ruby (surprise!)

And most relevantly:

I wrote YARD, a Ruby DocumentationTool: http://yardoc.org

http://gnuu.org/http://yardoc.org/http://yardoc.org/http://gnuu.org/http://gnuu.org/

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

3/47

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

4/47

Its not just aboutYARD

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

5/47

Documentation is

Important

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

6/47

Good Documentation

Is Hard To Find

NotVery

Helpful.

Copypasted

frombase class

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

7/47

Sad :(

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

8/47

Literally, Hard to Find

?

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

9/47

Bad Documentation

Can Be Serious Bad

Oops.

*snip*

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

10/47

Do YOU

document

your code?

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

11/47

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

12/47

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

13/47

RDoc

YARD

Ruby

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

14/47

RDocYARD

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

15/47

RDocYARD

* Note: not to scale

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

16/47

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

17/47

I dont have enough time.- Almost everyone

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

18/47

MakeTime.

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

19/47

Your users will like you.

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

20/47

Your users will like you.Your users wont hate you.

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

21/47

Your users will like you.Your users wont hate you.

Not everyone is going to read the source

And no, they shouldnt have to.

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

22/47

My code is self-documenting.- A lot of people

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

23/47

NO

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

24/47

Self-documenting doesnt scale1. Code gets complex whether you want it to or not.

2. Refactoring doesnt reduce complexity, it displaces it.

3. Simple English is always easier to understand.

defmake_request(opts = {}) parse_default_options(opts) HTTP.new( , ...)end

Great, but whatoptions?

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

25/47

Documentation is hard.- The people who actually tried

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

26/47

Fair enough.*

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

27/47

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

28/47

Rule #1: Consistent

Documentation is like code:

1. When you pick a style, you stick with it.

2. Specific conventions dont matter, following themdoes.

3. Lesson: Pick conventions and stick to them.

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

29/47

Rule #2: Correct

Documentation is like code:

1. It can be wrong.

2. You might not even realize it.

3. Lesson: Documentation should be AUDITED(tested) just like code.

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

30/47

Rule #3: Coherent

Documentation is like code:

1. It always makes sense to the person who wrote it.

2. It often doesnt make sense to anybody else.

3. Lesson: Documentation should be REVIEWEDjust like code.

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

31/47

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

32/47

Word Efficiently

Short sentences

Pay attention to vocabulary

Third person

Summarize in first sentence

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

33/47

Show andTell Examples are great

So are descriptions

Always try to specify parameter and returntypes

#@optionopts[Proc]:iftestsifmethodshouldrun

#@optionopts[String]:keysomeextraoptions#@return[void]defrun(opts={})#crazyrunstuffend

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

34/47

Just Say No to :nodoc:

Your users arent as dumb as you think.

Your end-users are not your only users.

Hiding code hinders re-use.

Just make it private?

defnode(xpath=nil)

node_at(xpath)

end

defnode_at(xpath)#:nodoc:

...

end

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

35/47

HARD?

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

36/47

begin

with_rdocrescue=>with_yard

yay!

end YARD!

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

37/47

YARDs Goals

Make it:

1. Consistent2. Correct

3. Coherent4. + Extensible (freebie!)

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

38/47

Consistent?

Meta-data @tags

#MakesanHTTPrequest

#@param[Symbol]req_type:getor:post

#@param[#read,nil]dataanypostdata

#@raise[IOError]ifasocketerroroccurred

#@return[void]defrequest(req_type,data=nil)

#...

end

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

39/47

Correct?

Write or roll your ownauditing tools

You have access to all the data.

You can extend YARD.

People are doing this:- DataMapper is a great example

- http://github.com/dkubb/yardstick

http://github.com/dkubb/yardstickhttp://github.com/dkubb/yardstickhttp://github.com/dkubb/yardstick

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

40/47

Coherent?

Mostly up to you, but again...

Easy to run automatedreviews (yardstick)

The HTML templates areeasy on the eyes!

E l f htt // d /d

http://yardoc.org/docs

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

41/47

Examples from http://yardoc.org/docs

A d h li d !

http://yardoc.org/docshttp://yardoc.org/docs

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

42/47

And yes, the online docs support comments!

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

43/47

Extensible?

Write plugins, themes,document DSLs, etc.

gem install yard-rspec- Shows RSpec specifications alongside method docs

gem install yard-sinatra- Documents Sinatra routes for your apps

gem install yard-pygments- Source highlighting for different languages

yard rspec

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

44/47

yard-rspec

yard sinatra

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

45/47

yard-sinatra

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

46/47

Conclusion?

The Ruby community needs better docs!

YARD is trying to make it easier to do! Start documenting your code!

Organize a hackfest todocument Rub stdlib!?

8/9/2019 Documentation and the Whole Nine YARDs (MWRC 2010)

47/47

You can host your docs on yardoc.org/docs too!

http://yardoc.org/http://yardoc.org/