Documentation? about mgo

[djensen47]

Is there another issue that's tracking documentation?

Right now, if you came to this library fresh, without the http://labix.org/mgo docs, you would not know how to Insert data nor get data out using a struct. Nor is there any clue that you can use a map (or not for that matter) instead of a struct.

[domodwyer]

Hi @djensen47

There's nothing tracking documentation at the moment, but feel free to open issues for specific things that you feel would benefit being included - we'll happily accept PRs for any improvements to the docs.

Regarding the example file, it's rendered in GoDoc, you don't have to go looking for the file so sticks with the "all in code" idea.

Dom

[domodwyer]

Hi @djensen47 - really sorry about the lack of a reply, I've been away at a conference for the last few days.

There's currently no plans for an accompanying site, it will add maintenance cost - personally I never looked at it! Is there something specific you used to rely on the labix site for? Perhaps we can find a way to work it in.

Dom

[cyberhck]

I believe we should have some documentation on readme, godoc etc. use cases, and stuffs. Right now this looks so empty.

[djensen47]

It was useful for setup and usually a docs page is more straightforward than a giant godoc page.

Documentation is a necessity of maintaining any great open source project (which this is 😄). It doesn't have to be a separate site but at the very least the project needs a README and a godoc.

[domodwyer]

I can see your point! Saying that, as an open source project we'll happily look at PRs improving the docs 👍

We've added a couple of code examples on the GoDoc page but it could definitely be expanded - it's preferred to use GoDoc as it's checked within the test suite - if a PR would cause the example code to become out of sync with the examples (say, in the README) this would cause a build error and would prevent a merge.

This fork was originally performance & bug fix driven - it was expected users already used mgo and were looking for a drop-in replacement, hence the light README as there was very little to say - again, we'll happily review PRs changing this!

Thanks,
Dom

[domodwyer]

Hi @djensen47

There's no plans to add an accompanying site / spreading the documentation over several sources - it only makes it trickier for newcomers to find what they're looking for and more work to keep it all in sync. Go strongly encourages documentation within your code which is automatically available on godoc which makes it the go-to place for everyone.

The basic insert/read operations you describe can easily be covered by adding examples to the code where everyone with a copy of the repo can access them, even offline.

We'll happily accept a PR to improve documentation on godoc in general, or maybe a quick-start markdown file within this repo though it would have to provide significant value to justify having documentation outside the official godoc documentation.

Dom

[djensen47]

Sorry, I wasn't clear ... I was literally just wondering if documentation is being tracked in other issues or if there is a tag? Some what to go about it in an organized manner.

it's preferred to use GoDoc as it's checked within the test suite

This was your original answer and it makes sense and I wanted to discuss that but forgot to say so (sorry). I would add that the Godoc route makes it easier to maintain.

---

Regarding the other stuff

it only makes it trickier for newcomers to find

I disagree. I've seen numerous examples from many programming languages where they do it right.

But I'm still totally on board with the Godoc approach. I've seen 2 or 3 Godocs that are complete and useful (which tells you the dismal state of Godoc docs) and that approach can definitely work.

The basic insert/read operations you describe can easily be covered by adding examples to the code where everyone with a copy of the repo can access them, even offline.

That file is really hard to see unless you know to look for it.

[djensen47]

So regarding Godoc doc bugs, should I file them individually, open it for discussion, then submit a PR? Or do you have another approach in mind?