RFC: website documentation

[dmathieu]

I believe one of the main reasons pliny isn't getting a lot of visibility at the moment is the difficulty there is to start understanding how it works and how to use it. There is a wiki documentation, but I don't think many people are led to it at the moment.

Proposal: A simple static website including the current documentation. This website can be included in a subfolder of this GIT repository, so documentation can be updated within code change pull requests.

We can run this website either using GitHub pages, or as a static site.

I'm going to try getting a designer to help us on that as well.

Alternative: We could also set that up in a different git repository, though it would make documentation harder, as any consequent code change would have to be in 2 PRs in 2 repositories. I don't think we're at a level where this added complexity makes sense. Though we might have to come to it when we need to support documentation for several versions.

[jellybob]

While more documentation would be welcome, at least for me the reason I wasn't using Pliny was that I had no idea it existed, rather than difficulty getting started with it. The current documentation was great at getting me going, and introducing the core concepts, I just wish I'd found Pliny months ago when we settled on Grape for our internal APIs at work!

[dmathieu]

@jellybob thank you for your feedback. How did you find out about pliny, and what would have helped in finding it sooner?

[jellybob]

I only found it because I happened to be poking around the interagent organisation after looking into Heroics - I'm pretty sure I've seen no mention at all of Pliny outside this repository. A quick Google shows that even when explicitly searching all that comes up is the repository, and a YouTube video from March.

[dmathieu]

That seems like an additional reason for setting up an actual documentation/guides place to improve our SEO.

[brandur]

+1! The docs for Pliny are incredibly lacking. Thanks for getting this thread started @dmathieu! (And sorry about the really slow responses on all these issues as of late.)

Before getting too deep into the technology: did you have any ideas around what the documents might look like and what kind of things we'd talk about? e.g. Would we try to write a guide like Rails has, or stick to a more basic API documentation for the time being? Should we just started by copying the whole Wiki en masse and leave it at that? This will affect things a bit because we're obviously at a bit of a content deficiency for a more comprehensive guide right now; it's possible we do something like try to get started with reference docs and then start to build out something that's more thorough/helpful.

One thing I've wanted to do for a while too is to write a super abstract set of guidelines like "Pliny principles" that represent the ideas behind pliny (e.g. composition over framework, isolate domain logic from endpoint implementation, start with a relational database, declaratively described API endpoints, etc.) and present that first as the highest level. From there allow users to dig in and look at documentation for the reference implementation of those principles, which is this project. The message would be that this project is a great way of getting started with abstract Pliny concepts, but they're also theoretically portable to any conceivable language and can even be integrated into existing projects.

Aside no. 1: I never really looked at it until now, but holy crap, so awesome how much wiki documentation @pedro and company have managed to assemble thus far. Amazing!

Aside no. 2: Wow, reading this thread reminded me of @will's awesome talk on Pliny.

[dmathieu]

Thank you @brandur. My thinking is to port the current documentation for now, and iterate on that. I don't think rails guides-style thing is necessary, as pliny is much smaller.

I'd very much like something like screencasts explaining basic or a bit more specific things, the overall idea being to get more adhesion on the project by having more visibility and making it easier for newcomers to start using it.

[brandur]

My thinking is to port the current documentation for now, and iterate on that.

Cool! Sounds reasonable to me.

I'd very much like something like screencasts explaining basic or a bit more specific things, the overall idea being to get more adhesion on the project by having more visibility and making it easier for newcomers to start using it.

Yeah, agreed. Well, hopefully we can expand once the basic pieces are in place.

[pedro]

Hey!

I like how wikis are easy to update and maintain, although wouldn't object a new site as long as it's still easy to update (and on that front I agree with you a folder on this repo is better than a whole diff repo).

And @jellybob has a great point, I think having blog posts and other sites covering Pliny would really help us get some traction. I personally just refrained from that so far because every time I work on the dreaded writing your first Pliny app I run into a different annoyance. Hopefully by smoothing more edges we can get to that point.

[brandur]

I like how wikis are easy to update and maintain, although wouldn't object a new site as long as it's still easy to update (and on that front I agree with you a folder on this repo is better than a whole diff repo).

+1! Keeping the bar to contribution (especially for documentation) is key.

One thing that we should probably make sure of is that we're moving to a new system for the right reason. If it's just that our SEO is bad, we may have some other possible avenues for improvement (even if it's just bigger links to it in the README and more numerous links elsewhere).

[gudmundur]

Hi everyone,

Thanks @dmathieu for taking this initiative. :fireworks: I've been thinking over this in the past few days and gathering my thoughts on this.

I like how wikis are easy to update and maintain, although wouldn't object a new site as long as it's still easy to update (and on that front I agree with you a folder on this repo is better than a whole diff repo).

+1! Keeping the bar to contribution (especially for documentation) is key.

I agree with this. A benefit of keeping the documentation in a folder this repo is that it'll be versioned along with the code. To attempt to keep the documentation up to date, we could add a "PLZ document" to the contributions guideline and on PRs.

If that's the direction we go in, it'll be easy to keep the static site generation separate from this repo, and store builds for every release.

Cheers, Guðmundur Bjarni

[dmathieu]

I like that idea of having markdown documentation within this repository and an external one doing the compiling and app deploy.

[johnbeynon]

Just to add my .2c here - I think one major reason for lack of adoption is authentication is missing, the wiki article doesn't exist. Rails has Devise and Doorkeeper, in Heroku we use an existing oAuth provider but a new project starting from scratch needs its own auth mechanism.

[gudmundur]

@johnbeynon Are you thinking that we should provide a description of how to set Pliny up with a OAuth2 provider or how to use something like OmniAuth with it?

[neilmiddleton]

I think one major reason for lack of adoption is authentication is missing, the wiki article doesn't exist.

I think one issue here is there's a lack of any examples really. Even a simple hello world sort of app using a mediator/endpoint and model. Even something simple will go a long way.

However, documentation is useless without eyeballs on it, so without awareness, docs aren't amazeballs. Things like this description isn't going to excite the sort of people that need this project, also, it doesn't even exist here.

Awareness is the first step (which a website of some kind would help), and docs is what makes it more sticky.