Please use the Apache issue tracking system for new NetBeans issues (https://issues.apache.org/jira/projects/NETBEANS0/issues) !!

Bug 167832

Summary: Providing more coverage to NetBeans Community Docs
Product: usersguide Reporter: nvarun <nvarun>
Component: CodeAssignee: issues <issues.netbeans.org>
Status: RESOLVED INCOMPLETE QA Contact: issues <issues.netbeans.org>
Priority: P2 CC: hmichel, jbranam, jeff_rubinoff, kawazu428, tusharvjoshi
Version: 3.x   
Target Milestone: TBD   
Hardware: PC   
OS: All   
Whiteboard:
Issue Type: ENHANCEMENT Exception Report:

Description nvarun 2009-06-29 20:39:04 UTC
This is the first time, I thought of filing an issue as I have never ever thought there would be a need for it, in the
past 2 years.

I have been an active contributor to NB Community Docs Program and managed it as coordinator for the duration of 11
months (May '08 - Mar '09). However, I feel there's lack of coverage of the resources we gather and arrange in the form
of several wikis interrelated with each other in a systematic way. 

Through this issue, I would like to see presence of NBCD in the NB Community. I have some ideas which I would like to
put forward, but first I want to see interest from your side.

Thanks!
Comment 1 Michel Graciano 2009-07-01 19:52:46 UTC
Hi Varun,
please share with us which are your ideas and details about which are your needs and how we may help you and NBCD.

Regards
Comment 2 nvarun 2009-07-01 21:27:14 UTC
Hi Michel,

Thanks for the response. Before I share my ideas, I would like to share some history about my ideas;
-----------
There are over 300 docs, right? When we reached 250 docs, I realised that there was findability issue. If I need a
tutorial on how to make use of some feature, which is documented only by a community member and not by Sun writers.
Then, user has to put some effort to locate that. Even I had that problem.

So, through mutual agreement, we created several category-specific wikis that would archive docs belonging to those
categories. You may read more about that here;
http://nb-community-docs.blogspot.com/2008/11/netbeans-community-docs-reloaded.html

This way we were able to fix the findability issue, temporarily. Yes, temporarily! I thought, we were still missing a
page which can provide pointers to all the sections of these category-specific wikis. So, I decided to setup a wiki:
http://wiki.netbeans.org/NBCDMatrix that will do the needful. You can have a look at this wiki.

Now, if anyone wants (community contributed) tutorials on GUI Builder, just need to bookmark this link;
http://wiki.netbeans.org/NBCDMatrix#section-NBCDMatrix-SwingGUIBuilder

This contains a matrix which has necessary pointers to tackle the issue.
-----------

Now, coming to the point of concern, i.e. the NetBeans Community Website doesn't feature pointers to these wikis. As you
might know that currently there's only one pointer to the Community Docs Contributions list from relevant Learning
Trails. Instead, I would love to see a separate "Community Contributed Docs" Learning Trails, where one can have
relevant information on how to access these wikis. Also, I would request the NB Team remove the following webpage;
http://www.netbeans.org/community/commdocs.html

Its better to have single Learning Trails page to focus on the above issue, rather than maintaining small sections on
every Learning Trail and maintaining the above webpage. It will also ease the work spent by NB Team on such maintenance.

Also, the proposed Learning Trail can also be pointed from User FAQs, Developer FAQs, etc. If someone is unable to find
necessary info in these FAQs, then he/she may navigate to the trail to learn how to find out community contributed docs
for their requirement. This should be good enough to make our presence felt in the community, as this L.T. would feature
in Docs & Support page.

Thanks!
Comment 3 nvarun 2009-07-06 20:29:53 UTC
There's no use of the Community Docs, if there are not being used and improved. That's only possible, when people are
aware about them. That's why I am increasing priority, as this has to be fixed, ASAP.

Michel, what you have to say about my ideas?
Comment 4 Michel Graciano 2009-07-06 21:05:48 UTC
I agree that we need to improve the docs webpage to link to wiki at all in an better way. Community docs, IMO, is just
one of docs umbrella that are not correctly linked from nb website. I am not an good person to say about layout and
organization in this area :( but I agree with your points. The point here is how to merge the docs from website and
wiki. Where do you think should '"Community Contributed Docs" Learning Trails' link be available? Probably as soon as we
have a place to put these, we can ask to help to do it. Did you already asked James to help about it? Maybe he can
contact correct people inside nb to make this happen as soon as possible.

Regards
Comment 5 nvarun 2009-07-07 08:42:46 UTC
Well, I thought that someone from docs team might assign issue to oneself and brainstorm over here. This has not
happened yet. Maybe as VOC captain, you can ask Jirka (Tech. Community Manager) to bring this issue to notice in the
eyes of concerned person. I can understand your point and if you agree with the ideas, you can vote as well.

To answer your question, I am interested having such Learning Trails over this page;
http://www.netbeans.org/kb/

When the user opens the concerned L.T., h/she will be directed to a page like;
http://www.netbeans.org/kb/trails/commdocs.html

This page will act as an interface between the community member and Community Docs program. This page would then have
necessary information about the wiki pages to refer to, why and when they must refer such docs, etc. Probably, once this
gets going, I can help in designing the webpage.

By the way, I have informed James about this issue and looking forward to his reply. Thanks for the help.
Comment 6 kawazu428 2009-07-07 11:38:10 UTC
Subscribed to and voted for this issue: Generally, indeed I think the NBCD documentation needs to be easier accessible
to NetBeans users stumbling across netbeans.org, the wiki seems much harder to find and/or use to some. However, I am
not sure how to do this right, as at the moment I have absolutely no knowledge about how NetBeans Knowledge Base
documentation is used, at all, and/or how NBCD in wiki.netbeans.org is used at the moment. @web-team: Are there any
access statistics for any of these resources available at the moment? 

Personally, though I generally like the idea of, say, "community-driven learning trails", I see getting them written
_and_ kept on a sane quality level being an outstanding task which (my opinion) so far can't be accomplished by the NBCD
team, looking at the overall strength of the team (in terms of people involved and/or contributing, most of them
unfortunately offering their rather limited spare time on the project). From that point of view, I'd rather like to
throw in considering how to, in the Knowledge Base, add these contributions the NBCD team is best at at the moment, most
notably being specialized tutorials addressing very special use cases and/or smaller or longer snippets of documentation
and code making everyday life easier to the IDE or platform user... 
Thoughts?

Cheers,
Kristian
Comment 7 James Branam 2009-07-07 12:37:19 UTC
Good points. I agree that there needs to be better visibility, but to get this visibility a few things must be considered:
- Docs need to be updated to the current version of the IDE. We have lots of great tutorials that could be listed on the
learning trail, but are for NB 6.0 (or even 5.5). We need to contact the authors and ask them to update the tutorials,
or we can find a volunteer to update them.
- Docs should adhere more to style rules in the style guide on the wiki. I'm not saying that a doc needs to be perfect,
but maybe just cleaned up a little.
- I still think that Kristian's idea of technology experts is a great way of going forward. Adding to this, such an
expert could also act as owner of a NBCD trail. Once we have NBCD trails for certain technologies, they become
compartmentalized and can be linked in a better way from each NetBeans learning trail. I think it's time that we push
this idea to the next level and ask for volunteers. What do you say, Kristian?
-  Also, Varun, maybe you could step up and work as a procurer of contributions. Blog monitoring, etc. What do you say?
- Remember, this is the community's program, not mine or Sun's. The NB docs community should decide what is best for the
program, etc. I'm here for guidance. 
Comment 8 kawazu428 2009-07-07 12:57:48 UTC
James;

you got some rather good points about this. To add a bunch of comments:

I think that, talking about this, more exposition of the project as a whole could eventually help attracting people to
volunteer here. I am not really sure what is the best way to do so. Maybe Kenai is a good place, maybe something like
"docs.community.netbeans.org" or whatever might be a valid approach as well (assuming NetBeans also to be a "community"
not just a bunch of Sun related people). At the moment, the project is mainly sort of "buried" amongst the
wiki.netbeans.org stuff which generally is not a bad place to be but rather hard to find at the very least, plus,
amongst most of the wiki stuff, I feel sort of a "scribble" notion about the community docs at times. This is not good.
About this, I strongly plead for choosing _one_ stable platform for the documentation to be used which meets all our
requirements and is straightforward enough not to waste our valuable resources on things like keeping a load of
different wiki pages, blogs, mailing lists, ... up and working. wiki.netbeans.org might be a place as good as any; I
generally would enjoy seeing "*.community.netbeans.org" subdomains usable for purposes like this...

Some more comments come to mind but they don't really belong here; I think at the moment having a "public"
representation better displaying "community docs" as part of the NetBeans community would seem sane. What about
something like...

http://docs.community.netbeans.org    ... for NBCD
http://dreamteam.community.netbeans.org    ... for NetBeans Dream Team
http://users.community.netbeans.org    ... for NetBeans users / usergroups / ... 
http://evangelists.community.netbeans.org    ... for volunteer netbeans evangelists and related material ?
Comment 9 nvarun 2009-07-07 13:20:06 UTC
James, 

Glad you replied, as you said its a community program, then why not take feedback from the community about this program
and its future as being discussed over here? Web Team can help in this by setting up a form and notifying everyone
through weekly newsletter, lets give them 7 days to give their feedback. Then, we will be in a better position to decide
what to do next. We can discuss how the form has to be put up for community. 

Some more points;

I agree with your points on adherence to style guide, updating docs, etc. However, it should be the responsibility of
the community, right? Sun won't be blamed at all. We as NBCD Team members can just guide them in the process, and should
not force them to do so. 

Let's just give it a try by getting their feedback by filling up a form and then, possibly setting up the L.T. I am sure
if community loves NetBeans, they would buck up themselves and help shape up the future of the program, whether its
adherence to some guides or updating docs to higher releases.

After all, NBCD L.T. will not feature links to the latest docs, in fact it will provide steps on how to effectively look
for a community contributed doc, with an example. Also, we will point them to necessary wikis, if there are interested
in contributing docs. Its basically going to be the homepage for NBCD.


PS: I'm sorry, I am free only for the next couple of weeks before I start working in a company. So, I won't be able to
monitor blogs, or manage contributions actively/regularly. Having said that, I can help our program move in right
direction in the next 2 weeks. 
Comment 10 kawazu428 2009-07-07 14:06:48 UTC
Folks;

I have a few fuzzy thoughts on that dumped to [1], maybe this would be a place to discuss the more NBCD-related issues
of this. At the moment I think this very issue here should find a viable solution how to make NBCD content accessible
from within the "rest" of the NetBeans web site...

Cheers,
Kristian

[1]http://wiki.netbeans.org/NBCDWhereToGoNext
Comment 11 Irina Filippova 2010-02-09 02:52:16 UTC
Added Jeff to the CC list. As the discussion needs to be continued, probably better to do it at the mailing list dev@usersguide.netbeans.org (just a suggestion)
Comment 12 nvarun 2011-01-26 18:11:36 UTC
Its been 2 years, I was unaware of the issue's status. I am closing this, as it no longer holds relevance.

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