RFC, Beefing up the docs

[davidyell]

I'd really like to contribute to the documentation. I think there is lots of room for improvement. However I am a little worried as I don't feel I know the plugin well enough to write accurate documentation.

I'm happy to make an effort and get the ball rolling. What is the suggested approach for this? I'm not a fan of readthedocs for a number of reasons, so what's the best way to submit my contributions?

My initial thought was to just fork and start working on markdown files in a /docs folder, but this seems to be where all the readthedocs stuff is. Then I thought it might be productive to create a github pages branch, but that seems to already exist as well.

If I can get some guidance and support, I'm happy write up the documentation to the best of my knowledge. I can mark parts which I'd like to cover, but need input on and hopefully someone can chip in on those parts.

[josegonzalez]

Rewriting to markdown is a bit silly, almost like making up busy work. There aren't any good alternatives - I should know, I heavily contribute to projects in this area, like viewdocs.io.

If you want to cover documentation on something, just submit a pr, and we'll review it. Also feel free to file issues for things you think aren't well-documented.

[davidyell]

I think it all needs redoing. Hence the title of the issue. I can submit individual issues, but there will be quite a few, and I doubt anyone will tackle them. Case in point the 'Building an API' section has been 'WIP' for ages. This is why I wanted to offer some time to help out, but not enough time to battle with Sphinx.

[josegonzalez]

Fine by me. You can have @ADmad hit me when they pop up.

[davidyell]

I'm disappointed with the response here. I was hoping for a discussion and I feel like I've been brushed off. This doesn't make me want to help out.

[lorenzo]

You can't expect to have a discussion without opposing views!

[davidyell]

No, that's true. I guess I'm stuck then, as I don't have the energy or time to deal with readthedocs.

I'll write a gist of notes for myself then, so I can reference that for things which I do.

[josegonzalez]

Why not open issues for each problem you see in the docs?

The other thing about meta issues like this is that it's hard to get anything actionable out of it. Turns into a wishlist. So if you think docs are lacking in some way - like the versioning thing you mentioned in irc - open an issue and we'll take a look at that specific thing.

Sorry for the heavy-handed response.

[jippi]

@davidyell i went from "hu" to "oh" in ~30min when i started writing the docs

its very mark-down'ish, and basically a clone of the cake book

the old manual was in markdown, but was quite inflexible and shitty to maintain

what challenges do you see in the workflow with the current setup?

[davidyell]

Upon reflection I actually agree with @josegonzalez. This issue was created out of frustration, which is never a good way to create an issue, for that I hold my hand up and apologise.

The docs do not need rewriting, however there are some areas which could be improved and some sections which could be added. The first case which springs easily to mind is convincing @bravo-kernel to add his API blog post into a docs page, so we can lose that 'API page is coming' message.

Other areas which spring to mind, are crud on prefix routing, customisation of flash messages, suggesting and showing integration with crud-view and foc/search.

I'll go through and make a proper list with explanations and ideas for each area, and then I'll open issues for those areas, and work on pull requests for the ones I can tackle.

The workflow with readthedocs isn't as big a deal as I make out. I just find it frustrating having to learn another markup language, but I manage to PR cakephp/docs just fine, so I should downgrade my whinge from earth ending to minor gripe 😉

Thanks for the understanding chaps, I should have probably had a quick chat in #friendsofcake before creating such a broad issue.

[jippi]

@davidyell readthedocs is sphinx, like the cake book - so its not domain specific to them

when i wrote the docs, i used sphinx locally while testing, only pushing to readthedocs when i was completely done :)

[bravo-kernel]

👍 for beefing up and restructuring the docs @davidyell . I will take care of the api section if I see progress.

[davidyell]

Hey @jippi are you able to assign this issue to me so I don't forget it?

[ADmad]

@davidyell GH seems to only allow assigning issues to those who have write access to repo :(

[ADmad]

I can send you weekly reminders 😛