search

apiaryio / apiblueprint.org

API Blueprint Website
https://apiblueprint.org/
MIT License
19 stars 42 forks source link

Meta documentation #103

Open toobulkeh opened 8 years ago

toobulkeh commented 8 years ago

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 https://github.com/thoughtbot/guides/pull/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 commented 8 years ago

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 commented 8 years ago
  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 commented 8 years ago

Walkthrough and explanation copy improvements

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

toobulkeh commented 8 years ago

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 commented 8 years ago

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

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

toobulkeh commented 8 years ago

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