Hi Ben, you wrote: >> >Thats where those guidelines are going to be helpful. As an author >who's interested I'm unsure as to what I can do. Can I add sections to >existing docs? Can I remove or rewrite major sections? Can I prepose >re-organization? Which docs can I contribute to? What are the steps >involved (ie: proposal, submission, review, etc)?
Yes, the guidelines. So, I think there are a number of sets of 'needed' guidelines appearing in different places. So, I want to ask you about this in more detail. I like the questions you pose above because it gives me a real sense of the type of guidelines you're in need of. I believe that the members of this community should be enabled to propose adding, removing, rewriting, and re-organizing any content that covers using the open code. I also see the need for information that describes: 1- authoring a piece (maybe by using a template, maybe just ASCII), 2- submitting a piece (maybe text entry field, or HTML entry field or wiki), and 3- maintaining a piece (maybe SGML/XML editor guidance or how to bringover src, get reviews, and putback). In addition, I think we might need information that: - guides us in how to write with consistent style, proper grammar, and terminology usage, spellign :) capitalization, graphics, etc. - specifies conventions for writing to a DTD when/if we choose to use one for appropriate pieces of this project (maybe this is roff or nroff first?) - guide to posting content on the OpenSolaris site (where, what, and whom to contact or notify, how to add your piece to the site doc index when/if we get one, etc.) - guide that describes how to make attributions, details the copyright and any legal considerations to make This is what I've heard about so far, just food for thought. I think all of these topics could go into one place as a library-type resource for us to use when we get started on a piece and to reference when we need information to support a decision about a piece. > >Working these things out better informs possible contributors but also >heads off any possible conflict ahead of time. No one likes proposing >something that gets immediately shut down as "out of scope". Agreed. > >I look forward to those guidelines, or a draft thereof. Great, I intend to propose a strawman outline so that we can all have a list of 'guideline topics' to use as a springboard for collaborative development. This will be 'cheap and dirty' at first, that is, it will be email exchanges. But, I have two draft 'entry/submission forms' that will coming soon so we can get a bit more sophisticated in future. > >>Agreed. I think we have to focus on the big goal of creating usable >>quality resource for all. Then, prioritize the types of documents. You >>say man pages are of most interest. What do others say? I'd like to >>enable contributions to other types of docs that have fewer >>complexities WRT attribution models, copyrights and structured tagging >>because it is already happening here in form of >>articles/blogs/infodocs, but without much coordination. I want to >>attempt to coordinate the types that are more flat first, because I >>think we are a bit 'stuck' on the man pages. But, maybe we need all >>hands on deck for the man pages and shouldn't move on until we have a >>working process for it?? >> >> >The man pages aren't of much interest to me, really, at least they are >low on my personal list. But, I consider the man pages as something to >fast-track because of the work being done on the code side. Some code >contributors have been frustrated by the inability to get changes or >corrections made to man pages, etc. Right now, today, they are the most >important because they are already up and running and producing, and any >barriers that can be removed from their paths, should be. Coders come >first. Agreed. > >Personally, I'm more interested in help, manuals, etc. But thats part >of an effort (which which mail is a part of) that is going to take a >little more time and planning. Yes, I appreciate your contribution to the planning--this is the kind of help that I need to ramp up and facilitate effectively. I'll help in any way that I can to clarify where we are, especially with respect to help and manuals, and to use the causal data from each inquiry to develop plans/processes that can survive long-term for the doc community. Thoughts? Thanks again! Michelle > >>I don't have the answers, but as a collective, we'll find solutions to >>these questions and they'll bring about more, tougher questions. >>Thanks again for this input, it is extremely valuable to me and to the >>effort as a whole. Keep 'em coming. >> >> >Definately. :) >benr.
