Skip to main content

This site requires you to update your browser. Your browsing experience maybe affected by not having the most up to date version.

We've moved the forum!

Please use forum.silverstripe.org for any new questions (announcement).
The forum archive will stick around, but will be read only.

You can also use our Slack channel or StackOverflow to ask for help.
Check out our community overview for more options to contribute.

Archive /

Our old forums are still available as a read-only archive.

Moderators: martimiz, Sean, Ed, biapar, Willr, Ingo

Please, please, please give us comments in the docs!!


Go to End


25 Posts   110583 Views

Avatar
blueskies

Community Member, 44 Posts

16 February 2008 at 12:10am

Edited: 16/02/2008 11:42am

I realize documentation is a very difficult aspect of complex code, especially with a critical and diverse open source community. But could you please, please, please open up the comments in the docs?! People could answer eachother's questions, give tips to modify/clarify the docs, etc (just like php.net).

I'm dying to post simple tips/tricks/own code to extend some of the docs and the forum is simply not a good place for that.

My current frustration is the doc http://doc.silverstripe.com/doku.php?id=imageupload
If I could just post a comment I would ask clarification on what "$Banner is taken from the class name, and PageBanner is the generated image." means... How is "$Banner" taken from the class name class Page_BannerImage extends Image {} or do you mean there is a form element in the backend called $Banner and that is the class name?

And if there were comments I would point out that there is a typo in http://doc.silverstripe.com/doku.php?id=develpoment-guidelines (check: develpoment), which is annoying ;-)

Avatar
Fuzz10

Community Member, 791 Posts

16 February 2008 at 12:47am

Cool idea !

I also LOOOOOVE the PHP website because of that functionality !

Avatar
dio5

Community Member, 501 Posts

16 February 2008 at 3:18am

Yeah, comments would be cool.

But if I'm correct, the docs are open to everyone if you login (at least I thought so, I can edit them), so I think we're all free to edit/add/modify and improve them.

Avatar
blueskies

Community Member, 44 Posts

16 February 2008 at 3:34am

@dio, thansk for the support!

No, I'm afraid I can't edit the docs. I get "This page is read only. You can view the source, but not change it."

But editing the docs would make a huge mess. If we'd be able to do it the PHP way, we'd be able to extend the main article, and make suggestions for an editor to edit the main article. That way there is a clear line between usergenerated stuff (possible errors) and the official Silverstripe docs.

Btw, as a sideline in case someone find this thread based on the imageupload thing and is pulling their hair out: the docs are missing an essential part:
static $has_one = array(
'HeaderImage1' => 'Page_Image', // This needs to be BannerImage instead of Image in order to extend from the newly created Page_BannerImage class ;-)
);

Avatar
Tim

Community Member, 201 Posts

16 February 2008 at 10:43am

Hi guys, requested noted, I'll see what I can do :-)

Avatar
Fuzz10

Community Member, 791 Posts

16 February 2008 at 11:42am

Great !! I think this will also lighten the load (pressure) on Silverstripe and the community to keep the documentation 100 percent up-to-date. Take the php site for example ; the docs are more or less user-generated 'self-help' pages (usually I end up finding the answer in the comments rather than in the 'official' docs).

Just like PHP does , the comments would have to be moderated well and SilverStripe should have the freedom to edit/delete the posts.. Here is a part of PHP's charter :

* If you are trying to report a bug, or request a new feature or language change you're in the wrong place.
* If you are just commenting on the fact that something is not documented, save your breath. This is where you add to the documentation, not where you ask us to add the documentation. If you have an addition or change request, open a Documentation Problem in our bug system, where your idea can be discussed.
* This is also not the correct place to ask questions (even if you see others have done that before, we are editing the notes slowly but surely). If you need support send email to the php-general list, or see what other support options are available.

If you post a note in any of the categories above, it will be edited or removed.

Just to make the point once more. The notes are being edited and support questions/bug reports/feature request/comments on lack of documentation, are being deleted from them (and you may get a rejection email), so if you post a question/bug/feature/complaint, it will be removed. (But once you get an answer/bug solution/function documentation, feel free to come back and add it here!)

(And if you're posting an example of validating email addresses, please don't bother. Your example is almost certainly wrong for some small subset of cases. See this information from O'Reilly Mastering Regular Expressions book for the gory details.)

Please note that periodically, the developers may go through the notes and incorporate the information in them into the documentation. This means that any note submitted here becomes the property of the PHP Documentation Group.

Avatar
blueskies

Community Member, 44 Posts

16 February 2008 at 11:46am

Edited: 16/02/2008 12:39pm

@tim
Thank you! Thank you! I think being able to post comments will be a very valuable addition to the docs. For the Silverstripe team and for the general community!

@Fuzz10
The general php.net guidelines sound great!

Avatar
Ingo

Forum Moderator, 801 Posts

18 February 2008 at 11:07pm

comments would be awesome, its a better repository for specific questions and tips, while more knowledgable community-members can still contribute to the (currently existing) open wiki.

dokuwiki has a discussion plugin (http://wiki.splitbrain.org/plugin:discussion), but its abandoned and i'm not sure about its performance and security. dokuwiki is filebased, and adding a comments-system might be overstretching its limitations a bit - so basically we might be looking at a good (php-based?) wiki-replacement - any ideas?

Go to Top