CommunityDocs ContributorHints

Revision as of 10:06, 28 May 2010 by Psunb (Talk | contribs)

Community Docs: Guidelines and hints for contributors

So you made it here in order to contribute documentation to the NetBeans Community Docs program - be heartfelt welcome here. In order to get you easily started, we collected a couple of resources and fundamental information on how the program works and how contributions should be added. We hope this will answer all your initial questions, if not, please don't hesitate contacting anyone of us with your questions and comments.

Contents


Why contribute?

There are a few good reasons to contribute documentation:

  • "Easily give something back": NetBeans IDE is an open source application with an enthusiastic community of users around the world. You don't have to be a software developer skilled in hacking the IDE's source code or spend a long time writing to contribute something. Every contribution matters whether short tips and hints or a brief guide to creating a certain type of project or configuring a 3rd party tool in the IDE.


  • "Community Recognition": As a community we show our appreciation to all those spending time and energy on sharing what they know. Who knows, your next employer may also care about your contributions to the NetBeans IDE and NetBeans RCP projects? :)

How to Contribute Docs Content

  1. First, check the docs wish list on this page to see possible topics for tutorials, tech tips, white papers, flash tutorials, blogs, etc. Please note that one subject can (and often should) be covered in several formats, so if someone has signed up to blog about something, that doesn't mean that someone else can't expand that blog into a full tutorial or flash demo.
  2. Send an email to the Community Docs Manager (jeffrey.rubinoff@sun.com), stating what you intend to contribute. If you choose to write a tutorial from the Wish List, add the list to the Community Docs in Progress Table with your name.
  3. When you are ready to publish your content, add the appropriate information to the Contributions Table on this wiki page.


Contribution lists

As you may already have found out, there are three lists maintained by NBCD team:

  • The main contribution list keeps track of all the documentation ever contributed to the program by any of its participants.
  • The work-in-progress list, as the name implies, is there to keep track of documentation just being written / created. Though not absolutely necessary, if working on contributions eventually taking longer to be completed, adding your work to this list is good practise in order to keep others from possibly starting a contribution covering essentially the same topic.
  • The wish list is there to collect documentation requests made by readers and users of NetBeans, and serves as an "inspirational source" for NBCD contributors when deciding which topic to cover next. Same as with the work-in-progress list, whenever you start working on a contribution, making a note on that in the wish list is good style and desirable, also to make users see their wishes are being dealt with.

Though we want to keep "administrative issues", i.e. copying / posting entries between lists, rather slim, there is a small workflow we would encourage you to adhere to in order to keep things somewhat sorted:

  1. Starting a whole new contribution? Add yourself to CommunityDocs_WorkInProgress.
  2. Adopted a wish list topic? Say so in CommunityDocs_Wishlist.
  3. Finished your work? Remove the entry from either wish list or work-in-progress list and move it to CommunityDocs_Contributions.


E-mail communication with the NBCD team

There is an dev@usersguide.NetBeans.org mailing alias available for discussing any issues related to NetBeans documentation and NBCD project, for asking questions about content, style, structure and the like, or for simply chatting and getting in touch with other NBCD contributors. We therefore encourage you to sign up for that alias and leave us a short note there. You may do so using the netbeans.org mailing list administration environment:

  1. Go to http://usersguide.NetBeans.org/servlets/ProjectMailingListList and log on with your user name. (If you don't have one, just click Login.Then you can register for one.)
  2. Scroll down to the dev@usersguide.NetBeans.org mailing list. Click subscribe and a subscription request will be sent.
  3. Within a few seconds, an email will arrive asking you to confirm the subscription. Just send an empty email back.


Contribution formats

  • Tutorials: Teach someone how to use your plug-in, or simply show someone how to perform a task using the NetBeans IDE. You can write a whole tutorial, or send us your list of steps and best practices that you discovered, and our writers will turn them into a tutorial. We will even provide you with a tutorial template.
  • Flash Demos: Demonstrate how tasks can be performed using the NetBeans IDE. You can make a Flash demo from any existing tutorial, or create a new Flash demo. Look here to see how to create a Flash demo.
  • FAQs: Do you have the answers? Add them to the User FAQ wiki page or write a short HowTo and link it here.
  • Tips and Tricks: Share ideas and give advice to other users. 'TaT' is intended to collect small yet valuable pieces of information helping you to get out the most of your tooling in everday productive work.
  • Blogging: Asides creating documentation right here in the NetBeans Community Docs wiki, you might as well use your weblog / website / content management environment / ... for doing so. Just add the URL or permalink of your contribution to CommunityDocs_Contributions or send it to us via e-mail so we will do that for you. If you intend to contribute regularly, you might as well consider adding your blog to Planet NetBeans.
  • 'Case Stories': Did you migrate your whole development team to using NetBeans and see significant benefit from this? Did you port your internal application to use NetBeans RCP? Do you by now offer to your customers an application based upon the platform, or do you provide a NetBeans IDE tooling for your very framework? No matter what, sharing your experiences on this also is a good way of contributing to the Communiy Docs program. Asides telling the world you're using NetBeans, this kind of contribution might come in helpful to both other users eventually into adopting NetBeans for a similar purpose. And, for sure it does help us learning what users are doing with 'our' application, it helps us responding to your experiences both positive and negative and overally making NetBeans even better, making it even more the tool you just want in your everyday productive work.


Style Guide

  • Editorial Guidelines for Submitted contributions by Catherine Pawlick. Here you'll find tips on making your contribution look neater and more professional. Though not completely required, this article definitely is a recommended read for anyone into writing technical documentation.
  • There is an article / reference sheet on how to use the wiki markup language in order to write structured documentation in this environment. Along with this, if you don't feel that well working with the somewhat bare-boned "plain" editor and have a Java plugin installed on your machine, you might as well use WikiWizard by selecting "WikiWizard" from the "Editor" drop-down box at the upper right corner of your editor window (which defaults to "plain").
Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo