Meta documentation about apiblueprint.org HOT 6 OPEN

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?

from apiblueprint.org.

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.

from apiblueprint.org.

Walkthrough and explanation copy improvements

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

from apiblueprint.org.

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.

from apiblueprint.org.

@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.

from apiblueprint.org.

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

from apiblueprint.org.