Meta documentation

[toobulkeh]

For a documentation standard, it sure was incredibly difficult to figure out the spec. (Your documentation is limited, and the GitHub interface was clunky as it overrides your files with MD previews which make it hard to read).

I would be interested in contributing to an initiative to build out the documentation more. Unfortunately I don't have the time/energy to lead that initiative, and I'm sure it's on a roadmap somewhere for you, but making it public may be worthwhile.

Side note, there's also some decent discussion at thoughtbot/guides#365 right now, and while APIary and APIBlueprint have some current shortcomings, I think it would be worthwhile for consideration into that discussion. I believe the current spec of choice is JSONapi.

[zdne]

thanks for your input @toobulkeh !

With

Your documentation is limited, and the GitHub interface was clunky as it overrides your files with MD previews which make it hard to read

You are referring to the examples (the examples folder)? The .md extension was added on purpose. Do you think using .apib (to not render it as Markdown and instead get syntax-highlighting) would make it more accessible?

I would be interested in contributing to an initiative to build out the documentation more. Unfortunately I don't have the time/energy to lead that initiative, and I'm sure it's on a roadmap somewhere for you, but making it public may be worthwhile

I will happily lead it. But your input is essential! What you think should be changed and improved in the first place?

[toobulkeh]

1. Move examples to the website so you have control over how they render, not GH markdown.
2. More examples (cover all features)
3. Shorter, more concise examples. "If X, do Y"
4. Walkthrough and explanation copy improvements.

I'm not a great copywriter, but I'd be happy to help if I can.

[pksunkara]

Walkthrough and explanation copy improvements

What exactly do you mean by this? Some kind of interactive tutorial?

[toobulkeh]

That could help for sure, but you already have 4 "examples" on the homepage that could be built out more.

You could chat with codeschool.com to see what an intro class with them costs, as they have a lot of skill at breaking things down to a learning pace. Just an idea.

[kylef]

@toobulkeh Just wanted to point out we've kicked off a new website:

• https://apiblueprint.org (source)

Does this solve some of your concerns? It doesn't yet have an example section, but it's planned.

[toobulkeh]

It looks pretty for sure, but I don't think it does some of the specific points I laid out above.