Documentation - Rewrote topics/access control #2444

Closed
wants to merge 1 commit into
from

Conversation

Projects
None yet
5 participants
@danbroooks
Contributor

danbroooks commented Sep 22, 2013

This started out as a couple of corrections and quickly turned into a rewrite.

Was going to carry on but I feel like there are other areas of the docs that need the work more than this page

+[Userhelp page on permissions](http://userhelp.silverstripe.org/framework/en/3.1/for-website-administrators/managing-roles-and-permissions).
+
+
+## Implementing PermissionProvider

This comment has been minimized.

Show comment Hide comment
@chillu

chillu Sep 24, 2013

Owner

Its an advanced use case, so probably should be further down the page

@chillu

chillu Sep 24, 2013

Owner

Its an advanced use case, so probably should be further down the page

This comment has been minimized.

Show comment Hide comment
@danbroooks

danbroooks Sep 24, 2013

Contributor

As a follow-on from my comment below - I'll try to add a simple example here to begin, just checking existing permissions with Permission::checkMember (checking if 'ADMIN' for example)

@danbroooks

danbroooks Sep 24, 2013

Contributor

As a follow-on from my comment below - I'll try to add a simple example here to begin, just checking existing permissions with Permission::checkMember (checking if 'ADMIN' for example)

@chillu

This comment has been minimized.

Show comment Hide comment
@chillu

chillu Sep 24, 2013

Owner

The content is in a lot better shape now thanks to your edits, but it duplicates some content already in place for http://doc.silverstripe.org/framework/en/trunk/reference/permission. I think we can migrate permission.md into access-control.md, what do you think? I think the correlation between permission codes in the database, security groups and PHP checks isn't entirely clear, maybe even less clear than before (https://github.com/dangerdan/silverstripe-framework/blob/b1113a45c1e7a161032d8c814fd64f86f611f746~/docs/en/topics/access-control.md). Could you work on paragraph at the end of the intro connecting those dots?

Owner

chillu commented Sep 24, 2013

The content is in a lot better shape now thanks to your edits, but it duplicates some content already in place for http://doc.silverstripe.org/framework/en/trunk/reference/permission. I think we can migrate permission.md into access-control.md, what do you think? I think the correlation between permission codes in the database, security groups and PHP checks isn't entirely clear, maybe even less clear than before (https://github.com/dangerdan/silverstripe-framework/blob/b1113a45c1e7a161032d8c814fd64f86f611f746~/docs/en/topics/access-control.md). Could you work on paragraph at the end of the intro connecting those dots?

@danbroooks

This comment has been minimized.

Show comment Hide comment
@danbroooks

danbroooks Sep 24, 2013

Contributor

That was a page I had my eye on working on as well while changing this page, though I only have so much time to write stuff.

I don't mind the idea of merging the two pages - but the fact they are in two different sections topic and reference, I would like to think that permissions.md would be more of a technical overview of this topic, whereas access-control.md be more of an 'advanced tutorial' style page. I'd say it's your call on that one.

What do you mean about correlating permissions codes, security groups and PHP checks? That the overall page doesn't imply enough that this is all an interconnected thing? I'd agree that it does dive in a bit too soon, I'll write something at the end of the intro to ease people into it.

Contributor

danbroooks commented Sep 24, 2013

That was a page I had my eye on working on as well while changing this page, though I only have so much time to write stuff.

I don't mind the idea of merging the two pages - but the fact they are in two different sections topic and reference, I would like to think that permissions.md would be more of a technical overview of this topic, whereas access-control.md be more of an 'advanced tutorial' style page. I'd say it's your call on that one.

What do you mean about correlating permissions codes, security groups and PHP checks? That the overall page doesn't imply enough that this is all an interconnected thing? I'd agree that it does dive in a bit too soon, I'll write something at the end of the intro to ease people into it.

@chillu

This comment has been minimized.

Show comment Hide comment
@chillu

chillu Sep 24, 2013

Owner

Given that access-control.md already goes into quite a bit of detail regarding PermissionProvider, and how short permission.md is, I think its fine to merge them. I'm starting to think that longer topics are better than too much fragmentation (seems to work well for Symfony2, see http://symfony.com/doc/current/book/index.html). The distinction between topics and reference has always been a bit weak, I think book vs. cookbook makes more sense, but that's a discussion for another day hehe.

What do you mean about correlating permissions codes

Yeah, explaining that the CMS is already setting up and using permission codes behind the scenes, but that its a PHP free for others to use and extend. On that note, it might also be good to mention DataExtension->canEdit() etc, with its tri-state checks (false, true or null).

Can you please try to compress the PNG as much as possible? The docs images are starting to become a real weight on our repo (git never forgets...), so I want to add as little overhead as possible.

Sorry to push so hard on getting this right, I really appreciate your work!

Owner

chillu commented Sep 24, 2013

Given that access-control.md already goes into quite a bit of detail regarding PermissionProvider, and how short permission.md is, I think its fine to merge them. I'm starting to think that longer topics are better than too much fragmentation (seems to work well for Symfony2, see http://symfony.com/doc/current/book/index.html). The distinction between topics and reference has always been a bit weak, I think book vs. cookbook makes more sense, but that's a discussion for another day hehe.

What do you mean about correlating permissions codes

Yeah, explaining that the CMS is already setting up and using permission codes behind the scenes, but that its a PHP free for others to use and extend. On that note, it might also be good to mention DataExtension->canEdit() etc, with its tri-state checks (false, true or null).

Can you please try to compress the PNG as much as possible? The docs images are starting to become a real weight on our repo (git never forgets...), so I want to add as little overhead as possible.

Sorry to push so hard on getting this right, I really appreciate your work!

@danbroooks

This comment has been minimized.

Show comment Hide comment
@danbroooks

danbroooks Sep 24, 2013

Contributor

No its okay, I think a bit of quality control is good :) going back and forth a bit with these changes has helped make them even better so it's all good stuff.

On the subject of reference vs topic could a lot of the stuff in reference actually be moved to the API docs? I always find the API docs to be weakest part of the documentation, and usually just end up using that site to navigate through source code... Potentially some of this stuff could be migrated to the API docs for the more technical, and the wordier stuff into topic (or book)? Again that could be a whole can of worms I'm opening here... anyway...

If I get chance tonight I will try and merge everything into this one file.

As a side note is it worth adding work that I have done into the 3.0 documentation (both these changes and my previous ones)? Or should I just leave that as it is?

Contributor

danbroooks commented Sep 24, 2013

No its okay, I think a bit of quality control is good :) going back and forth a bit with these changes has helped make them even better so it's all good stuff.

On the subject of reference vs topic could a lot of the stuff in reference actually be moved to the API docs? I always find the API docs to be weakest part of the documentation, and usually just end up using that site to navigate through source code... Potentially some of this stuff could be migrated to the API docs for the more technical, and the wordier stuff into topic (or book)? Again that could be a whole can of worms I'm opening here... anyway...

If I get chance tonight I will try and merge everything into this one file.

As a side note is it worth adding work that I have done into the 3.0 documentation (both these changes and my previous ones)? Or should I just leave that as it is?

@chillu

This comment has been minimized.

Show comment Hide comment
@chillu

chillu Sep 24, 2013

Owner

reference into api docs: We actually went the other way a while back, consolidating our more long-form docs into one place (markdown). But when we did that, the api docs weren't as easy to navigate, search or link to from docs as they're now, so we might want to revisit this. Do you have a good example of markdown docs which could move into a specific class?

Adding to 3.0 docs: Yes, I think for most docs work we should start out on 3.0. The 3.0 branch is regularly merged into 3.1

Owner

chillu commented Sep 24, 2013

reference into api docs: We actually went the other way a while back, consolidating our more long-form docs into one place (markdown). But when we did that, the api docs weren't as easy to navigate, search or link to from docs as they're now, so we might want to revisit this. Do you have a good example of markdown docs which could move into a specific class?

Adding to 3.0 docs: Yes, I think for most docs work we should start out on 3.0. The 3.0 branch is regularly merged into 3.1

@danbroooks

This comment has been minimized.

Show comment Hide comment
@danbroooks

danbroooks Sep 24, 2013

Contributor

Oh okay, with that knowledge I'll start making pull requests on 3.0 then :)

I don't know of anything in particular that could be moved to the API site, but I'd imagine some of the more technical usage examples could fit in well in the API docs. Even having this kind of info in the API docs would be good anyway I think, usage examples each class (atleast the key ones) would be a great boost for it IMO.

And for the lengthier stuff that is currently in reference, that could easily be merged into a topic - like you are suggesting we do with permission.

Lets take permission as an example - we could move the stuff from permission into the access control document, but also add some technical info (like usage examples) to the API docs for the permission class (like this does: http://api.silverstripe.org/3.0/class-FunctionalTest.html)

Contributor

danbroooks commented Sep 24, 2013

Oh okay, with that knowledge I'll start making pull requests on 3.0 then :)

I don't know of anything in particular that could be moved to the API site, but I'd imagine some of the more technical usage examples could fit in well in the API docs. Even having this kind of info in the API docs would be good anyway I think, usage examples each class (atleast the key ones) would be a great boost for it IMO.

And for the lengthier stuff that is currently in reference, that could easily be merged into a topic - like you are suggesting we do with permission.

Lets take permission as an example - we could move the stuff from permission into the access control document, but also add some technical info (like usage examples) to the API docs for the permission class (like this does: http://api.silverstripe.org/3.0/class-FunctionalTest.html)

@silverstripe-issues

This comment has been minimized.

Show comment Hide comment
@silverstripe-issues

silverstripe-issues Sep 24, 2013

I'm a bit wary about duplicating content between API and markdown docs,
but otherwise I agree that usage examples in PHPDoc will make the API docs a lot more useful.

On 24/09/2013, at 11:03 PM, Dan Brooks notifications@github.com wrote:

Oh okay, with that knowledge I'll start making pull requests on 3.0 then :)

I don't know anything in particular that could be moved to the API site, but I'd image some of the more technical usage style examples could fit in well in the API docs, even having this kind of info in the API docs would be good anyway I think, just being able to see a use case for each class that is in there would be a good boost for it IMO.

And for the lengthier stuff in reference, that could easily be merged into a topic - like you are suggesting we do with permission.

Lets take permission as an example - we could move the stuff from permission into the access control document, but also add some technical info to the API docs for the permission class (like this does: http://api.silverstripe.org/3.0/class-FunctionalTest.html)


Reply to this email directly or view it on GitHub.

I'm a bit wary about duplicating content between API and markdown docs,
but otherwise I agree that usage examples in PHPDoc will make the API docs a lot more useful.

On 24/09/2013, at 11:03 PM, Dan Brooks notifications@github.com wrote:

Oh okay, with that knowledge I'll start making pull requests on 3.0 then :)

I don't know anything in particular that could be moved to the API site, but I'd image some of the more technical usage style examples could fit in well in the API docs, even having this kind of info in the API docs would be good anyway I think, just being able to see a use case for each class that is in there would be a good boost for it IMO.

And for the lengthier stuff in reference, that could easily be merged into a topic - like you are suggesting we do with permission.

Lets take permission as an example - we could move the stuff from permission into the access control document, but also add some technical info to the API docs for the permission class (like this does: http://api.silverstripe.org/3.0/class-FunctionalTest.html)


Reply to this email directly or view it on GitHub.

@danbroooks

This comment has been minimized.

Show comment Hide comment
@danbroooks

danbroooks Sep 24, 2013

Contributor

I don't really mean putting the same content in two places. I mean lets take all the code examples that occur in reference and put them in the API docs, and all of the tutorial style/wordy content migrate into a relevant topic

Contributor

danbroooks commented Sep 24, 2013

I don't really mean putting the same content in two places. I mean lets take all the code examples that occur in reference and put them in the API docs, and all of the tutorial style/wordy content migrate into a relevant topic

@simonwelsh

This comment has been minimized.

Show comment Hide comment
@simonwelsh

simonwelsh Mar 15, 2014

Contributor

This needs to be rebeased before it can be merged.

Contributor

simonwelsh commented Mar 15, 2014

This needs to be rebeased before it can be merged.

@halkyon

This comment has been minimized.

Show comment Hide comment
@halkyon

halkyon Sep 25, 2014

Owner

No activity for a long time. Closing.

Owner

halkyon commented Sep 25, 2014

No activity for a long time. Closing.

@halkyon halkyon closed this Sep 25, 2014

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment