Improving API documentation readability

[MauroCoppola]

Subject of the issue

I saw that the README.md file also contains documentation for APIs but, unlike Table of Contents, it seems there isn't a clear separation between each explained API. That might make the navigation a bit less intuitive. Some ideas to improve it may be:

• Bulleted/numbered list for APIs;
• Indentation for API explaination;
• Dedicated .md file for API documentation;
• Particular style for API title to avoid misunderstanding with document's headers.

[wooorm]

@MauroCoppola Hello, nice to e-meet you! I like most of these ideas! But could you expand on the below points?

Indentation for API explaination;

I’m not sure what you mean with this 🤔

Dedicated .md file for API documentation;

Hmm, wouldn’t that make it harder to find stuff?

Particular style for API title to avoid misunderstanding with document's headers.

Don’t we already have that?

[wooorm]

@MauroCoppola What do you think about my previous comment? Anything I can clarify?

[bu7ch]

Can i take that.

[wooorm]

@MauroCoppola Ping!

@bu7ch I’m not sure yet whether this is an actionable issue.

[MauroCoppola]

@wooorm Sorry for my late response.

Indentation for API explaination; I’m not sure what you mean with this 🤔

and

Particular style for API title to avoid misunderstanding with document's headers. Don’t we already have that?

Those were some ideas to make a visual separation for each API explaination. For example, imho the Integrations paragraph seems a part of alex.text(value) API at first sight.

Dedicated .md file for API documentation; Hmm, wouldn’t that make it harder to find stuff?

Adding a link to the documentation inside README.md might avoid the problem. In addition, creating a dedicated file can be useful for the future if more APIs and/or more documentation for each of those will be added.

[wooorm]

@MauroCoppola Thanks for getting back to us!

Hmmm 🤔 I don’t feel like moving the API docs to a different place is going to help with readability / findability, as then humans looking for answers need to go to different places, and CMD+F doesn’t work anymore.

Also not sure why you see the integrations, at first sight, as part of the last API heading. The alex.text heading uses a smaller font that integrations.

And the API headings already have a different style: they are wrapped in inline code, so they already do look different from the other headings! 🤷‍♂️

P.S. I did find that the .alexignore heading should be indented an extra level and be “inside” Ignoring files

[Murderlon]

non-issue as currently presented