Poll : what documentation is missing in JNode ?
Submitted by Fabien D on Mon, 07/30/2007 - 23:30.
I have read somewhere on the web that JNode is missing documentation. I thinks it's true and may stop some people to work/start working on JNode so I am asking you all : what documentation is missing in JNode ?
Please comment and order by priority what kind of documentation you need to develop in JNode.
If I can write such a doc myself, I will do. If I know who can do it, I will ask that person.
Finally, if nobody knows that part, maybe you or someone else can starts learning that part and document it.
- Login to post comments
Needed Documentation
I am new to JNode.
I like the concepts behind JNode and hope to contribute to the project shortly.
What I would like to see are instructions on setting up an eclipse environment in windows that would allow for easy development and testing of JNode components. Perhaps a simple example on how to enhance a shell command. Test it and add it to the JNode OS.
I have JNode imported into eclipse given the instructions. Made some modifications to a few shell commands and tried to test. Keep getting an error where it can't find the main, even though it is there.
Noticed a number of typo's and grammer problems on the site too. Not sure how to go about getting those fixed up.
My first experimentaion with Jnode are in the shell area.
I am looking to enhance the Date command to add locale, formatting and time zone settings.
I was looking at providing a sort feature based on the linux shell sort.
Still getting my feet wet.
Thanks
It's a good way to start the
It's a good way to start the JNode development with improving and creating commands.
A 'sort' command would be actually pretty useful.
Docu updates
Regarding typos, grammar problems or missing stuff: Leave a comment to the documentation page and it will be built in to the page by someone with the permissions to do so.
If someone provides regular doc updates or intends to do so we can easily increase his permissions.
Well now that you mention it...
I'm taking a Software Engineering class this semester. As part of the course, I need to find an open source project and create/modify lots of high-level documentation, including Concept of Operations, Requirements, and the like. I selected JNode as I'm most experienced with Java and this project interested me. Here's the full breakdown of what I need to create in some form:
# Concept of Operations Document (first up, I'm working on it today)
# Software Requirements Document (I was planning on restricting it to Draft 0.3 additions and core functionality, unless people have more they can help steer me toward)
# Software Architecture Document (The overall structure of the system, I believe this can be compiled from clever re-usage of the Teams aspect of the project)
# Design Document (Full modeling of it all, though I'll likely simplify good bits as modeling an operating system is no small task)
# Test Plan (Not that far yet)
# Test Report (Not that far yet)
Since I'm required to create all of the stuff above, I hope that'd help with some of the higher-level documentation that right now is missing.
TaCktiX
David Bunn
Wanted: Architecture Documentation
An overarching architecture document is needed. I desire to read an architecture document to get the feel for the purpose and features of the software. Otherwise, the only other alternative is to reading through the documentation of a few dozen APIs and try to get a sense of the architecture.
Yes, the JNode system has an architecture. It is not one giant (monolythic) program.
Yes, architecture documentation is needed to present an accurate picture of the project. We should not require each participant to build their own picture of system architecture, should we?
To answer your question, the JNode system is actually composed of the following parts: builder, core, distr (distribution), fs (file system), gui (graphical user interface), net (networking) and shell. This architecture is reflected in software configuration management (SVN). It is partially reflected in the on-line website.
Why is the JNode system divided into these parts (and not other parts)? Simply dividing a system into parts does not explain why it was divided. An architecture document explains the purpose of dividing the system this particular way and what each part provides on behalf of the system.
Of course, architecture eventually becomes obvious to contributors of source code. Architecture documentation is not so much for contributors but for everyone else.
An architecture provides a place for everything. Let's say that I am looking for a particular feature. I should find it where I expect to find it. Let's say that I have developed a feature. I should add it where others expect to find it.
Wasting time is a Bad Thing. Who has an infinite about of time to research the JNode project in order to determine if it is suitable for a particular purpose? An architecture document enables one to get a sense of the project without wasting precious time.
An architecture document includes the current status for each part of the system. It enables part of the system to be "complete"--without waiting for the entire system to be complete.
An architecture document demonstrates that this is not an all-or-nothing decision. Or, do we believe that not one class out of 5,000 classes is ready for any real world application?
Those documents could be useful to us
However, I'd note the following:
If I was advising you (as a student), I'd suggest that you pick a much smaller project to document. Something <100K lines of source code would be a good idea; <20K even better.
Or maybe just limit yourself to (say) the JNode command shell and related libraries. That's a pretty complex bit of functionality and there is already a bit of ad-hoc documentation for it.
Not to worry on size
Thanks for the reply. I've been backed up school-wise for a couple weeks and haven't had a chance to drop back by since. I consulted with my professor and he agrees with my viewpoint: JNode's size is not an issue as all documentation I am to provide is high-level. I am not supposed to, nor am I interested in line-by-line documenting JNode. On the high level, I don't need to worry about 5000+ classes spread across hundreds of branches, just the five major focuses (denoted by teams) of development.
As for whether or not JNode can benefit from this high-level documentation, it only stands to gain. Documents like ConOps and the Software Architecture Document are meant to be written in plain English, defining for the uninitiated what the project is about. You've got stuff like that right now, it's just spread around in 6 or 7 places. Consolidating it will allow people to say "go here, it'll explain what the project is."
I've attached a first version of the ConOps document I've drawn up. Any refining comments would be most appreciated, and I'll try to revise it as soon as I get comments.
Creating documentation for
Creating documentation for JNode is a useful activity, so please keep up the good work and submit here the results so that we can review and comment on it. I can only second the comments of Peter.
Thank you!
Good job
You have accomplished your goal to provide a brief, conceptual overview of the JNode project operations. Good work.
What about teams? Such an overview might drive a healthy discussion toward a more accurate picture of how the project operates. Maybe the project had more formal "teams" when it began. Maybe the project will grow so much that formal "teams" will be needed. Like you, I was under the impression, for example, that a specific person is the leader in the Shell team/component.
Does it make sense to run JNode without core? without shell? without fs? without gui? without net? If the answer is always no, JNode has no optional parts and cannot be physically divided.
It has conceptual parts: kernel, JVM, standard Java class libraries, JNode class libraries.
Comments
Hi TaCktiX,
I've read your document and will make some minor comments. I can not comment to the content of your document regarding the size, level of detail or the completeness of features/concepts (Mainly as I'm not sure about the expectations for a document like that).
You write: "To speed development, five design teams exist". One might get that impression when having a look at our site. But imho the reality is a bit different. There are those 5 components you named, but they are separated due to their nature of operation and on the source level, too. But they are not separated into "teams" anymore, mainly due to missing man-power. In practice anyone is commiting to any part of the source base. So I would rephrase everything that has the word "team" in it, e.g. using the word "component" or something like that.
Your figure and explanation suggest that FS, Net and GUI depend on the Shell. In my opinion the Shell is orthogonal to the other parts.
I'm missing a more explicit view on the "only java code"-feature. Perhaps you could name the nanokernel too which is a base for the Core and a native code for the initial bootup and setup, but I'm not quite sure if this is to much detail already.
You describe the plugin framework and its gains quite well. But in your last paragraph the "ability for performance" is imho not based on the plugin concept but on the JIT, design-concept,.. (only java code so you can dynamically optimize down to the driver level, you don't have expensive mode switches, ..).
Hope that helps, but before you change over to my comments (especially that on the "teams") you might want to wait for someone else's comment, too.
Wanted: JavaDoc documentation
JavaDoc documentation is missing. As a system architect, I want to look at an operating system at a very high level, the package level and higher. When completed, JavaDoc documentation increases the comprehension of the APIs.
It answers questions about feature such as:
Does it exist?
Has someone thought of it already, possibly under a different name and terminology?
How much effort is required to write a plug-in? a command?
Thanks,
At least provide a single download link on the download page
Hi,
I'm new here.
I discovered the the 'printer friendly page' link in the documentation section of the site provides a single page with all the documentation.
At least give this link more visibility, and add it to the main download page.
Brett
New Feature
Thanks for the hint. I didn't expect that subpages get displayed as well but I like it very much. This must be a new feature of drupal. I didn't recognize this in the old forum.
Drupal + DokuWiki
Just to throw my two unasked-for U.S. cents into the mix, I have seen very good results with integrating DokuWiki[1] into Drupal, allowing for
shared logins and CMS + Wiki capabilities.
One plugin for DokuWiki, called Discussion, seems to be a good fit for this site as well. The Discussion wiki allows people to saved threaded comments on a wiki page as meta-data, rather than modifying the page content itself. This allows the articles to stay relatively on-topic, yet still have threaded discussions related to the page linked right to the page, like those on the Drupal nodes now. The discussion piece can also be linked to a separate page like MediaWiki's talk tabs if you like.
There are a ton of other DokuWiki plugins I could see as well, such as the Blog plugin with links to the Drupal user pages, or a user:username wiki page, and more. If someone does install Doku, and you have questions about it, feel free to e-mail me or IM me about them.
[1] DokuWiki http://wiki.splitbrain.org/
--
Robert "Exile In Paradise" Murphey
I think you're right
I think you're right Fabien, we need a better documentation. At this moment we have a lot of it, only thing is, that beside our documentation section, it's spread out all over our forums and one have to do a lot of searching and have read the threads as they was written. It would be a help if we could collect whats allready pressent into a common document.
Martin
I want to express my
I want to express my opinion about documentation too, so I'll do that now:
I personally would prefer if we switch to mediawiki for our documentation but also keep drupal for normal forum discussions and user questions. The reason I like mediawiki is, that anyone may help to enhance the documentation. There are for sure many people (also noobs) that could help make JNode docs better, write new docs or only correct the language (native speakers). Even if someone writes a documentation page that has many errors, I belive that it will get corrected very soon because of the nice way to track changes and see diffs.
I don't like track that much because it would fully replace drupal and would have the same downsides for documentation.
And I don't like openoffice or something like that because it makes it very hard to track changes (binary diffs *shrug*). It will be usefull for a complete user-documentation perhaps, but I don't think we're at a point to need that yet. Imho we need a simple and easy doc-system to track stuff that is needful for other developers and "users".
About spam: At the moment we have a high amount of those §"%*$&, but we manage to delete it very quickly imho. And afaik we're only 3 guys that have permission to delete spam at all. With mediawiki I'm sure there would be many more that would (and could) delete spam. Imho spam wouldn't be a real problem with mediawiki. (And Fabien just noted that there are even patches to mediawiki to include spam filter for submissions)
To note that again, that's my opinion and probably not shared by all other developers
Open up the task of write documentation
The task of writing documentation needs to be opened up and made easier.
Currently, the only way I can write documentation is to write it offline and submit it as patches. AFAIK, there are currently only 2 people who are able to / have time to make changes to the online documentation pages. The project should be set up to allow JNode users (especially native English speakers!!) to contribute and update documentation rather than making it hard for them to do this.
The second problem is that the platform we are using for creating / presenting documentation is too primitive. For example, since articles can't use <pre> or <verbatim> tags, it is next to impossible to put properly formatted Java code into an article. Perhaps the this can be addressed by alter configuration parameters, updating to a newer version, etc. If not, we need to move to a better platform.
Finally, I'm not convinced that raw HTML (or some Wiki markup) is the right medium for writing documentation. IMO, it would be better to use a fully fledged document format / editor (e.g. ODF / OpenOffice) with appropriate document styles and conventions.
Using TRAC is better for us
hai,
all
It is true that we need more enhancement in the JNode's Documentations.That will help all.
My proposal(i told to FabienD already about it) is to use TRACK for seeing a WIKI like Web Content Site for JNodeDOCs.There we can create our JNode Wiki as a Wikipedia site.As the current Documentation portion will need major changes.So, Using Track we can get it easily.
An example site who are using the Track for their Doc's page is YASM.
IS it not better?what is your opinions? Reply frankly
Thanks
tanmoy
I have tried both Track and
I have tried both Track and Jira (and some other ones), and to me Jira outruns all other issue trackers I know off. But having our documentation in such a tool seams to me not the right way of documentating a project. Still I think that we might be thinking of using Jira as our issue tracker.
Martin
Mantis bug tracker
Hi Martin,
What do you think about Mantis bug tracker ?
I have never used it but heard it's a good bug tracker and much configurable (so it should probably fit our needs for bug tracking).
Fabien
my blog (in english and french)
No Wikis, no HTML
Both Wiki and HTML quickly become messy. I'm with the other guy. It needs to be done in Open Office.
The lack of professional doc is holding us back from quick-try users. There are LOTS of people who'd give this project a whirl if the documentation was decent. Java heads abound, and we can probably get more casual interest (plus maybe additional interest and committers). But most people don't have 2 days to dedicate to getting all the disparate parts together just to get everything working.
Dereck