CommunityDocs ContributorHints

Revision as of 21:08, 4 November 2009 by Admin (Talk | contribs)
(diff) ← Older revision | Current revision (diff) | Newer revision → (diff)

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.

[[{TableOfContentsTitle=TableOfContents} | {TableOfContents title='Table Of Contents'}]]

Why to contribute after all?

If you just came here incidentially, you might wonder why to actually spend your time and work on writing documentation after all. There are a few good reasons to do so:

  • "Easily give something back": Like so many other projects these days, NetBeans is an open source application built and driven forth both by Sun engineers and a vivid worldwide community spending time, energy and enthusiasm on the project. We're glad to see our tool making your everyday work more productive and enjoyable, but we also will be happy seeing you join us making this project even better and bigger. To contribute something, you don't have to be a software developer skilled in hacking NetBeans source code to fix issues and implement enhancements. You also don't have to spend hours and hours per week working on the project. Every contribution matters, and if you just wanted to share this tip or hint you just discovered with other users worldwide and spend these fifteen minutes on writing it down, that's perfectly fine with us. NetBeans Community Docs is a perfect way of contributing even if you don't have that much time to spend on this.
  • "Real-life documentation for day-to-day users": Documentation provided along with a software system needs to meet many different requirements; being an end user, you're likely to want documentation explicitely focused on your everyday work with that very piece of software, on making you more productive and achieving better results in a short period of time. From that point of view, you're likely to get the most out of documentation provided by someone who shares this point of view, who also is mainly an everyday user sharing personal experiences, insights, best practises, tips and tricks in using the tool to do productive work. Knowing about the potential of our users sharing their experiences and knowledge, we want to link people and collect these information in a central place for the benefit of all users. Maybe already by tomorrow it might be you finding the hint or tutorial to quickly resolve some questions you've been dealing with the last couple of weeks.
  • "Improving NetBeans as a whole": Using the tool on a daily basis, you get a pretty good understanding of how to do things right. Maybe in some situations the way how the tooling expects you to do things could be improved, eventually being more intuitive, requiring one less workaround to be written down and recorded? Share your experiences with other users as well as with NetBeans developers and help us making a better tool!
  • "Be recognized by the Community and beyond": After all, writing documentation in here is not for "nothing". As a community, we indeed want to know who our most active contributors are, and we will definitely show special appreciation to all those spending time and energy on growing this project. And, who knows, maybe your next employer also might care about NetBeans IDE, NetBeans RCP and your contributions to the project? ;)


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