Parse-server: Documentation concern

[grosscorporation]

I am really concerned about the pace at which changes and releases are being pushed arbitrarily with no documentation. Ever since we upgraded to 3.0 one needs to be fully following the repo to catch-up as some of these changes have gone under the Radar with no consideration or updating of the docs. I hope I am wrong about this and that this wonderful project does not become a project for a select few. Its important to note that this project has since stopped growing and I am beginning to wonder if its not worth it to just migrate back to firebase.

[acinader]

Thanks for sharing your concern. Could you give us a couple of examples?

[davimacedo]

@GoGross thanks for your feedback. I have some comments:

• Changes and releases are NOT being pushed arbitrarily by anyone. All changes and releases pass through a PR approval process in which they are discussed. You are more than welcome to contribute to the discussions as well if you believe that something should not be pushed/released. You can even open a discussion about something that was already pushed and the community can decide to revert.
• I believe that most of the documentation lack that you are referring is regarding the GraphQL API, right? We've launched a first version of the API in order to get feedback from the community and we actually got very valuable ones. Some discussion was taken around this and we decided to improve the API, which requires some breaking changes. So we added the beta alert here and docs about this and started to working on these changes. We are few steps do conclude these changes (at least the main ones) and remove the beta notice.
• Anyway, the documentation was up to date until the release 3.8.0 and not yet updated for the release 3.9.0, but I'm personally working on this right now.
• Regarding the other features that were added/changed recently, most of them were documented. If you are noticing the lack of documentation for any of them, let us know.
• And, yes, I agree with you that we still have a historical documentation debit. We are trying to improve the documentation always that we can and you are also more than welcome to contribute on this either adding more docs or pointing out what you think it is missing.

[dplewis]

As a community based project, we try to do as much as we can and naturally the documentation grows over time.

The Changelog of every release should inform users of updates. A million line documentation guide wouldn’t help. We do respond within 24 hours (maybe later) for any request that may already exist or could be implemented.

I do agree the guides are lacking and a cross language documentation like stripe has been brought up. Hopefully somebody in the community helps out.

Unfortunately my time is spent on performance and new features. I could stop adding new feature and focus on docs, or do both

[grosscorporation]

@davimacedo

I truly acknowledge the release process, it's just that that's all there is, without pointing any fingers, I just feel that it would be great to update the docs as well, especially the API, for example, @dplewis the allowHeaders option doesn't appear anywhere in the docs, and many others with each release

[davimacedo]

@GoGross the allowHeaders are actually there: http://parseplatform.org/parse-server/api/master/ParseServerOptions.html

[grosscorporation]

hey @davimacedo can you donate the dashboard index manager to the repo, I like it on b4a

[davimacedo]

I thinks it is off topic here, but, yes. We have pushed some of b4a dashboard changes to the community and the index manager can be eventually pushed as well. It is not so easy though, because it works highly coupled with the deployment architecture.

[dplewis]

I feel the guide should be about basic parse features, CRUD operations for SDKs. The API references are auto generated and has almost everything. A single new feature require a PR on different SDKs and a similar PR for each guide. it’s a lot of work but somebody has to do it.

[mtrezza]

I am really concerned about the pace at which changes and releases are being pushed arbitrarily with no documentation. Ever since we upgraded to 3.0 one needs to be fully following the repo to catch-up as some of these changes have gone under the Radar with no consideration or updating of the docs. I hope I am wrong about this and that this wonderful project does not become a project for a select few.

• I think there is a quality and actuality difference between the Guide and the API Reference. While the API Reference has historically been quite up-to-date (because it is generated from in-code-docs), the Guide usually lags behind. Which makes sense, because writing a prose form with nice formatting and code examples is a task in itself. And for the sake of project agility it seems viable to break down the implementation of a new feature into smaller tasks which don't have to happen all at once. One of these tasks would be writing the Guide docs.

• Being a community project and given the contributor community size I think it is viable to merge a feature with only the API reference docs. However, the contribution guides surely could emphasize more why adding the Guide docs is beneficial for other users and the project.

• When you don't find something in the docs and you are undergoing the effort of researching in code, feel free to open an issue and contribute to the docs.

Its important to note that this project has since stopped growing and I am beginning to wonder if its not worth it to just migrate back to firebase.

Looking at the recent change logs in parse server, parse dashboard I have the opposite impression. There seems to be a steady addition of useful features. Some SDKs may not be updated as frequently, but there has been an overarching discussion about GraphQL possibly replacing the need for SDKs altogether. That is a topic open for discussion.

[TomWFox]

As a follow up to @mtrezza’s point about encouraging the documentation of new features. I think it would be a good idea to use pull request templates to highlight key points of the contributing doc such as providing documentation.

[omairvaiyani]

Here, there are clearly some very good concerns and equally good suggestions to mitigate them. I'll add one such suggestion, and hopefully we can get a plan underway to make sure everyone's happy, on the same page and can see the roadmap ahead.

There are a few too many locations that store information for users looking to learn, or finding solutions. Instead of having the github README, and github Wikis and parseplatform.org guides - we should just remove the wikis, have a short README that just points users to the guides and work towards a cross-language guide:

• I don't think GraphQL will replace SDKs in their entirety anytime soon
• Parse-Server guides should be merged with Cloud-Code

A community questionnaire to determine usage behaviour and statistics will greatly inform the future roadmap.

[TomWFox]

I totally agree on removing wikis and README content, happy to take that on.

[mtrezza]

Another minor thing, it would be nice to see release notes consistent across repos.

For example, the new release of Parse iOS SDK has all changes in the change log, but none mentioned in the release log which can be confusing.

[TomWFox]

@mtrezza Ha, as you've noticed, I fixed that specific example, but yes changelogs should be a lot more consistent, @omairvaiyani suggested some packages/conventions we could use here.

[davimacedo]

I love the ideas here and I think that we can really have a much better documentation experience by moving forward with them!

I've just created a project so we can track the progress of the ideas we generated here and in some other threads: https://github.com/parse-community/parse-server/projects/8?add_cards_query=is%3Aopen

Feel free to change/suggest changes to the tasks and grab any of them for execution.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.