What's the plan for docs.meteor.com?

core
1

Now that Meteor 1.3 is out and the Meteor Guide is shaping up nicely, what is MDG’s plan to fix the API docs, if any?

There are about 100 documentation related open issues on Github issue tracker. Some basic features like reactive-dict and Meteor.defer are not documented and there are useful other public functions missing as well. We find the API docs invaluable so I’d love to see/help get them fixed up.

If nothing else I’d like to see some of the low hanging fruit and open pull requests accepted. A quick re-organizing could be done in a few hours as well to better match what ships in 1.3 and I have some specific ideas, but I don’t want to waste my time if there is a plan to move from current Meteor app approach with JSDocs to something else like static hosted pages on Github (which would be great long term).

1 Like
2

I think ideally we would move the docs onto an infrastructure very similar to the guide, with static pages, a version selector, and continuous deployment. I’d love to still keep the source code comments as the source of truth, but maybe that’s not necessary and makes stuff harder to update?

1 Like
3

I personally think having api docs generated from the code is really nice as it allows you to quickly see, while looking at the source, if a function is documented without having to hunt it down in the actual documentation.

The problem with continuous deployment of API docs separate from the actual source code releases is things can get out of whack. It is manageable, but then requires management.

Can you get an official MDG plan in place and communicate it out sometime soon? At least then we can figure out if we should spend any time trying to fix up current API docs (or not).

4

I think the best option is to have the actual arguments and function definitions come from the code, then have some extra content for code samples, helpful links, etc. We can do this with an automatic build process that pulls from the meteor/meteor github.

I don’t really know what a “plan” would be. Anyone could do this today, it’s just a question of whether we get to it soon or not. The steps are:

  1. Make a new repo based on the guide
  2. Modify the build step to clone and get the docs data: https://github.com/meteor/meteor/blob/devel/docs/client/data.js
  3. Create a template that renders the API doc data
  4. Migrate markdown content from the docs

Definitely not - I think a new website is the way to go.

5

OK, I think you answered my question. MDG is not currently “planning” on putting any resources on fixing up the API docs, correct?

6

I think we’re currently focusing on fixing bugs reported after the 1.3 release.

7

Bug fixes are definitely higher priority in the short term then fixing up docs. However, it would make sense to put out a doc plan at some point, especially if you want to get help from the community.

8

Keep the source code comments as the source of truth!

2 Likes
9

If anyone is interested in helping out with the legwork, I’d be happy to write a more detailed plan! Do you think people would pitch in?

1 Like
10

Can’t speak for other people on this particular topic, but I have a little bit of time to spare for this, since we’re maintaining API docs for the Clinical track over at http://clinical-api.meteorapp.com/.

I’d like to keep what we’re doing in sync with what MDG is doing. That being said, I’ve been experimenting with adding support for Blaze helpers and Nightwatch commands in the docs page. Not sure if anybody else has been working on improving the docs site; but there might be some potential features available from our fork.

2 Likes