which API ref should be kept and updated `README.md` or `api.md`?

[Connoropolous]

Shouldn't keep both because that makes keeping them up to date confusing and hard. I am happy to help, if people have a preference which one to keep.

@dominictarr @mixmix @christianbundy can you advise?

[christianbundy]

Thanks for bringing this up!

My personal preference is to keep readme files small, so I'd prefer to link to the API file from the readme. All opposed?

[Connoropolous]

Yeah, I'd propose linking from the README into that file as well. It could be a bit of a job merging the best of the two, I tried doing a quick diff compare but the diff was too general to be useful

[Connoropolous]

@christianbundy you self-assigned this, what does that mean or indicate in your world, or the ssb world?

[christianbundy]

I'm not sure whether others are using this model, but I've been self-assigning issues and pull requests to indicate that they're on my personal road-map for the future of SSB. This has a side-effect where assigned issues are immune from the stale bot, so as long as there's an assignee the issue won't get marked as stale or closed.

[dominictarr]

history: api.md was made to back in the early days, and the muxrpc manifiest was generated from it, also it got dumped for cli help, but it didn't work very well. also it never really got updated. so readme became the main thing. recently I made a much better cli help. that's in help.js and https://github.com/ssbc/muxrpc-usage I'm not against dropping api.md

muxrpc-usage documents api options down to the level of options, but it doesn't cover things that are callable from JS but not cli. does any one think it would be useful if a md was generated from that? I'm a tad reluctant to add buildsteps if not necessary.

[gmarcos87]

I'm trying to improve the documentation of several ssbc packages. Among them ssb-db. I wish I could solve this issue at the same time. The pull-request is #279
Should I remove the api.md file?

[Connoropolous]

I am thinking so, as long as the docs have been evaluated to make sure that nothing in api.md is missing from README.md.

[mixmix]

Proposal

We remove api.md and README.md becomes the primary source of info for developers

---

3 thumbs up from regular maintainers = this will happen.
Leave comments below if you're STRONGLY against

[stale]

Is this still relevant? If so, what is blocking it? Is there anything you can do to help move it forward?