Jump to:

17452 Posts in 4473 Topics by 1971 members

Archive

SilverStripe Forums » Archive » Please, please, please give us comments in the docs!!

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

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

Page: 1 2 3 4
Go to End
Author Topic: 109238 Views
  • blueskies
    Avatar
    Community Member
    42 Posts

    Please, please, please give us comments in the docs!! Link to this post

    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 ;-)

  • Fuzz10
    Avatar
    Community Member
    787 Posts

    Re: Please, please, please give us comments in the docs!! Link to this post

    Cool idea !

    I also LOOOOOVE the PHP website because of that functionality !

  • dio5
    Avatar
    Community Member
    501 Posts

    Re: Please, please, please give us comments in the docs!! Link to this post

    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.

  • blueskies
    Avatar
    Community Member
    42 Posts

    Re: Please, please, please give us comments in the docs!! Link to this post

    @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 ;-)
    );

  • Tim
    Avatar
    Core Development Team
    201 Posts

    Re: Please, please, please give us comments in the docs!! Link to this post

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

  • Fuzz10
    Avatar
    Community Member
    787 Posts

    Re: Please, please, please give us comments in the docs!! Link to this post

    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.

  • blueskies
    Avatar
    Community Member
    42 Posts

    Re: Please, please, please give us comments in the docs!! Link to this post

    @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!

  • Ingo
    Avatar
    Forum Moderator
    801 Posts

    Re: Please, please, please give us comments in the docs!! Link to this post

    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?

    109238 Views
Page: 1 2 3 4
Go to Top

Want to know more about the company that brought you SilverStripe? Then check out SilverStripe.com

Comments on this website? Please give feedback.