Hi Ben, THanks for your response, I appreciate you giving me more details of your concerns and ideas. you wrote: > >Thanks for the reply Michelle. Congrats on taking a leadership role in the Docs community. > >The problem with the existing roadmap is that I don't see where the community fits into that plan. Its not untill Phase 3 that the community is involved, and then we're only able to pair up with a sponsor.
Agreed. Along the path DocBook comes into the picture, but if SolBook isn't made avalible then I don't see why community standards can't be put in place now. Agreed. Naturally Epic can't be handed out (although it would be really kool), but Epic isn't a requirement, its a convience; if we've got SolBook we can use our existing editors and toolchains to produce documentation. > >I look forward to meeting you at the SVOSUG meeting, but the bulk of the authors are here, not at SVOSUG which is limited by physical scope. Discussion and debate needs to occur here. Understood. All conversations should end up at very least being summarized and submitted for more input here. > >While I understand that the "writters list" that you maintain is a list of internal authors... the _real_ authors list is here: http://opensolaris.org/os/blogs/ OK, so let's not be us/them in the reverse direction. We are all real authors. My list is an attempt at encouraging internals to participate, not at separating and dividing. So, I take this as good feedback and I'll change my tack there. > >The direction this community has been on, as reflected by the roadmap and discussion to date, seem to be far too limited in scope. This is all about, it seems, allowing external authors to contribute to internal documentation, whether that be man pages, help reference, or full-on manuals. Excellent, this is great input that I will add to the roadmap, I agree that the scope is too limited, so let's work together to expand it. But it is my believe that these are of less pressing concern and of those three its man pages that are of most interest. While we'd all love to work on the official Sun documentation, there is no attribution model at this time, making contribution a questionable thing untill we've figured that out; a classic problem for contributions to inhouse techpubs. Agreed, we need to open the pieces that align with the open code. Attribution model must come with this effort. > >The immediate concern of this community should be, imho, to act as a hub for the various documentation efforts occuring across the globe in the community. There is current a sort of "us vs them" vibe due to the lack of coordination which has lead to massive duplication. Yep, I thank you for bringing the elephant out of the room. Duplication is a symptom of the us/them problem and I agree that coordination is the key to making progress here. As a leader I hope to help coordinate members of this community to reduce duplication where it hurts users and causes confusion for them. There is the Sun manual on docs.sun.com, then there is a PTR book, then there are magazine articles, then there are blog entries and online articles, then there is a guy in Norway with a site devoted to the topic, so on and so forth. We have here the oppertunity to try and bring all this together and create a unified effort that minimizes duplication, encourages involvement and attribution, and provides the most targeted and useful set of resources for the people that truly matter most: the end users. I am so glad to have you involved in this way, Ben, I really am becuase you hit the nail of it here. We have a great opportunity to do more for users and we all have that common goal. I believe this is the goal that should bind us in the effort. I've considered, in this last week, that a brief charter describing this would be a nice baby step toward more focus. I think your statement above is the best version I've seen yet. > >We can begin by simply cataloging what exists. Yep, Ginnie drafted an index for the OpenSolaris site that we discussed yesterday--I got background from her before I responded to you :) Now, I think you're talking about something much much bigger here and I will go ahead and say that I think the actual scope is somewhere in between 'everything that exists' and 'everything on the OpenSolaris site'. Providing some guidelines on how to best coordinate our various efforts. Right. We now have a model that says to contact a sponsor for any contribution. As a brand new person to the community, I found this limiting and I was surprised by it myself. And, it seems that we need to build some credibility as sponsors and I will work on that by just being here. In fact, I just found out that we have two excellent writers who have volunteered to sponsor doc contributions as they come in, so I will work closely with them to improve coordination. Enlist experts to work together with authors, and vice versa. > >The Sun doc team is producing quality documentation and doing a good job. But external authors are producing hundreds of pages of documentation every day. If a documentation community is going to be worth its salt it can't stay focused purely on what is in reality only a small subset of the true information base avalible. 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?? 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. -Michelle > >benr. >This message posted from opensolaris.org >_______________________________________________ >docs-discuss mailing list >docs-discuss at opensolaris.org
