CommunityDocs ContributorHints

(Difference between revisions)
(Why to contribute after all?)
m (unemote)
 
(17 intermediate revisions not shown)
Line 1: Line 1:
__NOTOC__
__NOTOC__
-
==Community Docs: Guidelines and hints for contributors==
+
==Community Docs: Guidelines and Hints for Contributors==
 +
 
 +
In order to get you started quickly, we collected the resources and essential  information about how the program works and how to add contributions. If you don't find the answer here, send an email to commdocs at netbeans.org .
-
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.
 
__TOC__
__TOC__
-
===Why contribute?===
+
===Why Contribute to Community Docs?===
There are a few good reasons to contribute documentation:
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.
+
* '''"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 hints or a guide to creating a certain type of project or configuring a third 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?
-
* '''"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===
===How to Contribute Docs Content===
-
# 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.
+
* Have a short tutorial, tech tip, demo, plugin guide or blogs entry to share? There are a couple ways you can share it:
-
# 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.
+
-
# When you are ready to publish your content, add the appropriate information to the Contributions Table on this wiki page.
+
 +
* Create a wiki page on this wiki using the [http://wiki.netbeans.org/BriefTutorialOutline BriefTutorialOutline] template as a guide. When you think the content is ready, send the link and announce that it is ready for review to commdocs at netbeans.org . After it has been reviewed we will add the link to the [http://wiki.netbeans.org/CommunityDocs_Contributions Community Document Contributions].
-
===Contribution lists===
+
* Write about it on your personal blog or DZone. When it's ready, send the link to commdocs at netbeans.org and we'll add it to the community contributions list.
-
As you may already have found out, there are three lists maintained by NBCD team:
+
* Want to contribute but don't have an idea what to write about? Take a look at the [http://wiki.netbeans.org/CommunityDocs_Wishlist document wish list]. There are plenty of topics yet to be written about that could benefit from your insights and experiences using the IDE.
-
* The [[CommunityDocs_Contributions| main contribution list]] keeps track of all the documentation ever contributed to the program by any of its participants.
+
-
* The [[CommunityDocs_WorkInProgress| 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 [[CommunityDocs_Wishlist| 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:
+
===Discussing Contributions on our email alias and forum===
-
# Starting a whole new contribution? Add yourself to [[CommunityDocs_WorkInProgress | CommunityDocs_WorkInProgress]].
+
There is an commdocs at netbeans.org mailing alias that links to a forum (add URL) for discussing any issues related to NetBeans IDE Community contributed documentation such as asking questions about what to contribute, how to contribute and request reviews of contribution. from other contributors. We encourage you to sign up to commdocs at netbeans.org or visit the [http://netbeans.org/projects/www/lists/commdocs/archive mailing list archive] to see what is being discussed.
-
# Adopted a wish list topic? Say so in [[CommunityDocs_Wishlist | CommunityDocs_Wishlist]].
+
-
# Finished your work? Remove the entry from either wish list or work-in-progress list and move it to [[CommunityDocs_Contributions | CommunityDocs_Contributions]].
+
 +
* To Sign up to the mailing list go to [http://netbeans.org/projects/www/lists http://netbeans.org/projects/www/lists] and log on with your user name. If you don't have a user name just click Login and register for one.
-
===E-mail communication with the NBCD team===
+
* Scroll down to the commdocs at netbeans.org mailing list. Click subscribe and a subscription request will be sent.
-
 
+
-
There is an [mailto:dev@usersguide.netbeans.org 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:
+
-
 
+
-
#Go to [http://usersguide.netbeans.org/servlets/ProjectMailingListList 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.)
+
-
#Scroll down to the [mailto:dev@usersguide.netbeans.org dev@usersguide.NetBeans.org] mailing list. Click subscribe and a subscription request will be sent.
+
-
#Within a few seconds, an email will arrive asking you to confirm the subscription. Just send an empty email back.
+
-
 
+
===Contribution formats===
===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 [[BriefTutorialOutline| tutorial template]].
+
* '''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 just a short list of steps and best practices that you discovered. You can use the [[BriefTutorialOutline| tutorial template]] as a guide for how to format your contribution.
-
* '''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 [http://www.NetBeans.org/kb/articles/CreateWinkDemo.html how to create a Flash demo].
+
* '''Screencasts:''' Demonstrate how tasks can be performed using the NetBeans IDE. You can make a demo from any existing tutorial, or create a new one. A guide to how to do this using free software is at [http://www.NetBeans.org/kb/articles/CreateWinkDemo.html http://www.NetBeans.org/kb/articles/CreateWinkDemo.html].
-
* '''FAQs:''' Do you have the answers? Add them to the [[NetBeansUserFAQ| User FAQ wiki]] page or write a short [[HowTo | HowTo]] and link it here.
+
* '''FAQs:''' Do you have an answer to a question that should be on the FAQ? Then share it by adding it to the [[NetBeansUserFAQ| User FAQ wiki]] page or write a short [[HowTo | HowTo]] and send the link to commdocs at netbeans.org.
-
* '''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.  
+
* '''Tips and Tricks:''' Share ideas and give advice to other users with small, useful pieces of information to help with getting the most out of the IDE in everyday work situations.
-
* '''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 | 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 [http://planetnetbeans.org/ Planet NetBeans].
+
* '''Blogging:''' You can use your weblog or other website where you've been published for creating contributions too. Just send the link to commdocs at netbeans.org .
-
 
+
-
* ''''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.
+
 +
* ''''Case Stories':''' Did you migrate an entire development team to NetBeans IDE and see productivity improvements? Did you port an internal application to use NetBeans RCP? Do you offer to your customers an application based upon the platform? Sharing your experiences is a good way of contributing to the Communiy Docs program. Aside from telling the world you're using NetBeans, this kind of contribution might offer insights to other users considering a move to  NetBeans IDE for a similar project. It also helps ''us'' to understand what users are doing with the IDE and how to make it even better.
===Style Guide===
===Style Guide===
-
* [http://wiki.netbeans.org/DocEditorialGuidelines 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.
+
* [http://wiki.netbeans.org/DocEditorialGuidelines Editorial Guidelines for Submitted contributions] by Catherine Pawlick. Here you'll find tips on making your contribution look neater and more professional. This guide is recommended for anyone who writes technical documentation.
-
* There is an article / reference sheet on how to use the [[TextFormattingRules| 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 [http://www.i3g.hs-heilbronn.de/webcasts/wikiwizard/wikiwizard_demo.html WikiWizard] by selecting "WikiWizard" from the "Editor" drop-down box at the upper right corner of your editor window (which defaults to "plain").
+
 
 +
===Working In The MarkUp Notation===
 +
* [[TextFormattingRules|Wiki MarkUp Notation]]
 +
* [http://extensions.services.openoffice.org/project/wikipublisher Sun Wiki Publisher] is an extension for Open Office and [http://www.libreoffice.org Libre Office]. It is available as a package for various OS distributions, sometimes named as [https://packages.debian.org/libreoffice-wiki-publisher libreoffice-wiki-publisher].

Current revision as of 13:27, 6 March 2014

Community Docs: Guidelines and Hints for Contributors

In order to get you started quickly, we collected the resources and essential information about how the program works and how to add contributions. If you don't find the answer here, send an email to commdocs at netbeans.org .

Contents


Why Contribute to Community Docs?

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 hints or a guide to creating a certain type of project or configuring a third 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

  • Have a short tutorial, tech tip, demo, plugin guide or blogs entry to share? There are a couple ways you can share it:
  • Create a wiki page on this wiki using the BriefTutorialOutline template as a guide. When you think the content is ready, send the link and announce that it is ready for review to commdocs at netbeans.org . After it has been reviewed we will add the link to the Community Document Contributions.
  • Write about it on your personal blog or DZone. When it's ready, send the link to commdocs at netbeans.org and we'll add it to the community contributions list.
  • Want to contribute but don't have an idea what to write about? Take a look at the document wish list. There are plenty of topics yet to be written about that could benefit from your insights and experiences using the IDE.

Discussing Contributions on our email alias and forum

There is an commdocs at netbeans.org mailing alias that links to a forum (add URL) for discussing any issues related to NetBeans IDE Community contributed documentation such as asking questions about what to contribute, how to contribute and request reviews of contribution. from other contributors. We encourage you to sign up to commdocs at netbeans.org or visit the mailing list archive to see what is being discussed.

  • Scroll down to the commdocs at netbeans.org mailing list. Click subscribe and a subscription request will be sent.

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 just a short list of steps and best practices that you discovered. You can use the tutorial template as a guide for how to format your contribution.
  • FAQs: Do you have an answer to a question that should be on the FAQ? Then share it by adding it to the User FAQ wiki page or write a short HowTo and send the link to commdocs at netbeans.org.
  • Tips and Tricks: Share ideas and give advice to other users with small, useful pieces of information to help with getting the most out of the IDE in everyday work situations.
  • Blogging: You can use your weblog or other website where you've been published for creating contributions too. Just send the link to commdocs at netbeans.org .
  • 'Case Stories': Did you migrate an entire development team to NetBeans IDE and see productivity improvements? Did you port an internal application to use NetBeans RCP? Do you offer to your customers an application based upon the platform? Sharing your experiences is a good way of contributing to the Communiy Docs program. Aside from telling the world you're using NetBeans, this kind of contribution might offer insights to other users considering a move to NetBeans IDE for a similar project. It also helps us to understand what users are doing with the IDE and how to make it even better.

Style Guide

Working In The MarkUp Notation

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