NBCDWhereToGoNext

NetBeans Community Docs - where to go next?

Please add your initials in bold to add your comments and add an entry in the following table;

Initials Full Name Email Id
KR Kristian Rink kawazu428 AT netbeans DOT org
VN Varun Nischal nvarun AT netbeans DOT org


[[{TableOfContentsTitle=TOC} | {TableOfContents title='TOC'}]]

Getting to know the user

  • KR: The best documentation is useless if no one is reading it.
  • KR: Do we know who is reading our documentation?
  • KR: Do we know whether reading them provides benefit to anyone?
  • KR: Do we know whether people actuall manage to find our documentation?
We should try to find some answers to these questions...


  • KR: ... making use of evaluation forms in some particular pieces of documentation ("Was this article useful to you?", similar to the Sun knowledge base)
  • KR: ... making use of, if possible, server and access logs to figure out whether people made it to the NetBeans Community Docs pages and (if so) how long they remained there and where they went next (Google Analytics, anyone?)
  • KR: ... making use of quick means for users to request documentation on a very specific article (i.e. by adding a "request documentation" form to the official NB knowledge base knowing that eventually this request will be dealt with by some NBCD contributor)?


Contributing and sorting content

  • KR: Potential contributors should not initially be scared off by having to use a wiki editor to contribute documentation. They should, after all, contribute.
  • KR: Maintaining documentation (i.e. updating articles to reflect changes in recent IDE versions) should be even more straightforward as this is likely to be a "boring routine task" which should be easy as possible.
  • KR: Likewise, "administration" of contributions should be easy as somewhat possible. Everyone so far who's into writing weblogs knows about things like "categories" or "tags", and knowing this few people will understand why someone has to "link" a contributed piece of documentation to a whole couple of different pages ( NBCDMatrix, contribution list, ...) when just adding a few tags would provide the same effect. This also would allow for finding "similar" documents (containing similar tags and/or being filed to similar categories).
  • KR: For "end users", finding documentation quickly should be the top priority.
  • VN: I have found a way to categorize the docs as per the NetBeans IDE, they are applicable to.
  • VN: Proposing five short steps (try it out) to access relevant docs quickly.
We should reconsider contributing and filing documentation to make it easier


  • KR: Can we provide sane templates to those who want to contribute via the wiki?
  • KR: Can we provide tooling and technology for people to i.e. write documentation using their NetBeans IDE editor and, say, a subversion client?
  • KR: How can we provide an "auto-sorting" documentation collection by using tags, categories, ..., eliminating the need to manually link contributions around?
  • KR: How can we allow users to quickly browse documentation in a sane, straightforward manner? delicious.com as a navigation example?


Environment and technology

  • KR: We don't have resources to waste. We should focus on technology helping us as good as possible by requiring as little effort as somewhat possible.
  • KR: Focus things in one central place, make it work as good as it can.
Being a community and not directly bound to netbeans.org/Sun, we should focus on doing a quick requirements collection and, then, look for a place to meet these requirements as good as possible (kenai?)


Requirements

  • KR: Quick and straightforward addition / contribution of documentation (weblog/wiki-like)
  • KR: Contribution / document maintaineance also possible using external editors and SVN/CVS/mercurial/<insert-your-favorite-RCS-here>
  • KR: Sorting of articles automatically using tags, categories, date/time
  • KR: Templating support (optional?)
  • extensive RSS support (changes in total, changes per category / tag, changes done to a given article, ...) to allow users for being notified if something of interest to them changes
  • KR: allow for "syndication" of external sources (planet-like?) to allow users to contribute documentation using their favorite environment (personal weblog/wiki?), in best case automatically at least archiving contributions

Feature Comparison Matrix

(Newly Added) }}sortable

Features Required (?) Kenai Sourceforge
Chatroom KR: optional Yes No
Version Control KR: yes (if usable) SVN, Mercurial, Git SVN, Mercurial, Git, CVS, Bazaar
Downloads Section KR: yes Yes Yes
Wiki Syntax KR: yes MediaWiki MediaWiki, Wikispaces (default)
Issue Tracker KR: yes Bugzilla, JIRA TracWiki, MantisBT, Tracker (default)
Forums KR: optional Markdown, BBcode phpBB
Mailing Lists KR: yes Yes Yes
Blogging Platform KR: yes None Wordpress
Micro-Blogging KR: optional (evaluate usability) None Laconica
Code Review KR: optional None CodeStriker
Survey support KR: optional (sounds like a good idea) None LimeSurvey
Web Analytics KR: yes None Piwik
Task Management KR: yes JIRA TaskFreak, Task Manager (default)
Project Management KR: optional (do we need this?) None dotProject


Related Comments/Suggestions

(Newly Added)

  • VN: I feel although a chatroom might not be a necessity, there must be provision for VCS and Downloads.
  • VN: Issue Tracker is a must, so that the core members of the team can manage tasks, RFE's and resolve issues.
  • VN: Surveys are necessary to take a regular feedback about the program.
  • VN: Micro-blogging not necessary, but blogging will be necessary if we take the approach of reposting the existing docs as blog entries and add new one's along the way. This way, we would be able to tag the docs as per NB release, feature, docs_format.
  • VN: As we aim towards integrating the program currently spread over social networks, blogs, wikis, etc. at one place. Mailing Lists, Forums support might help the cause as well.
  • VN: Wikis would then serve the purpose of defining ways how to access relevant docs, posted as blog entries and providing guides on various issues, etc.


Maintaining quality

  • KR: We want to have a high-quality collection of documentation.
  • KR: We have limited manpower to ensure so, and this is likely to stay this way at least for a couple of months.
We should consider solutions to...


  • KR: ... attract more volunteers to have some at hand to be "spared" on doing QA exclusively,
  • KR: ... ease maintaineance of documentation to make this work more "straightforward" to community contributors
  • KR: ... thus, more or less indirectly, solve 0 .. 3


Braindumps

Dealing with Updates

  • Problem:
  • Documentation might cease to be meaningful with a new release of NetBeans as the technology documented therein might more or less drastically change.
  • As general size of NBCD archive grows, reviewing and updating all contributions will be increasingly resource-consuming.
  • Solution ideas:
    1. Collect "votes" / page views / whatever per documentation piece. Define some sane threshold for documentation to qualify for review / update for compatibility with next NB release ("all documents with > n votes"? "the 25 documents most viewed / voted for?" ...?). Everything else "just" gets archived "as-is". Vote / view counters to be reset with release of a new NB version.
    2. "Weblog approach": generally keep contributions "as-is", update only "if requested" (i.e. user stumbling across a piece of documentation asking to review that for "the current NB release"). requires straightforward mechanism for end-users to request "review". "review" of contribution to result in either (a) "works-with-NB-X.Y"-badge immediately, (b) "updated-for-NB-X.Y" after doing required modifications, (c) contribution being archived as "obsolete" (discarded?!) if content has become meaningless.


Survey insights

  • NBCD: generally a good idea
  • provide info on "hidden" features of the IDE undocumented in the official knowledge base
  • Docs should be up-to-date and/or labeled to know which NB version they have been checked with.
  • NBCD is difficult to find, having "one list of documentation in one place" seems a good idea. sorting generally leaves to be desired.
  • Documentation related to building real-world plugins leaves to be improved.
  • Screen casts seems to be the type of documentation the fewest people see as important.
  • Searching for docs by language, "related docs", tags or learning trails seems to be desirable over the wiki search.
  • Technical problems (wiki editor) don't seem to keep people from contributing; language problems and the feeling not to be "knowing" enough to contribute, however, seems to.
  • A lot of people got aware of the survey (and, thus, of the NBCD project itself?) via the "Starting screen" showing news feeds inside the IDE.
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