luckyframework / luckyframework/website

Add reusable way to reference API documentation pages

Open
#644 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Crystal
Stars
39
Forks
62
PR merge metrics
No merged PRs in 30d

Description

With Crystal shards like Lucky, we really have two areas where "official" documentation is kept:

I think we do a fantastic job of driving traffic to luckyframework.org, but not such a good job at driving traffic to the really great built-in API docs.

What got me thinking about this was some recent work with Lucky::Params. The Guides pages focus on the "standard" way to organize a form, which is the correct thing to do, but because my usecase wasn't there, I ended up stumbling through the source code for a while and just trying a few things. Then, I remembered we have API docs, and within a few keyword searches for "params", I was able to find the Lucky::Params#from_form_data method I needed.

I think it could be really cool to have a common convention in our Markdown for referencing specific API pages (not methods, since that would be annoying to maintain). Something like:

If you're reading this content, you'd probably find these API documentation pages helpful for more details:

Maybe we store these in an array with each guide definition, or something? I didn't want to open a PR in case y'all had already considered and decided against this, but I think it would be a great way to both encourage folks to use the API docs as a resource, and encourage us to improve and keep them up to date.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing how the site's guide definitions and Markdown content are organized, then compare the existing guide links with the Lucky and Avram API documentation URLs mentioned here. Decide where a reusable API-page reference convention belongs and document the expected format; done means guides can use it consistently without maintaining individual method links.

Written by the indexing model from the issue text.

Assessment

Tech stack
crystal
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.