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.

Archive

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

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

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


Go to End
Reply

25 Posts   109356 Views

Avatar
blueskies

16 February 2008 at 12:10am (Last edited: 16 February 2008 11:42am), Community Member, 42 Posts

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

16 February 2008 at 12:47am Community Member, 787 Posts

Cool idea !

I also LOOOOOVE the PHP website because of that functionality !

Avatar
dio5

16 February 2008 at 3:18am Community Member, 501 Posts

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

16 February 2008 at 3:34am Community Member, 42 Posts

@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

16 February 2008 at 10:43am Core Development Team, 201 Posts

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

Avatar
Fuzz10

16 February 2008 at 11:42am Community Member, 787 Posts

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

16 February 2008 at 11:46am (Last edited: 16 February 2008 12:39pm), Community Member, 42 Posts

@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

18 February 2008 at 11:07pm Forum Moderator, 801 Posts

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