Re: [oi-dev] OpenIndiana Docs (proof of concept) - What is it all about?
Michael Kruger писал 04.05.2016 08:00: Now that the dust has settled a little bit after my initial presentation, perhaps I should elaborate a bit about my motivations and intentions in creating this little proof of concept. I just want to summarize discussion on IRC... We are not sure if all of the documentation, which was earlier present on http://dlc.openindiana.org/docs/ is redistributable, so we preserved only one archive (docs-20090715.tar.gz), in which we are sure. It's contents in unpacked form is available at http://dlc.openindiana.org/docs/20090715/ . It is a temporary location. Ideally, this documentation should be reviewed, perhaps converted to other format and updated. --- System Administrator of Southern Federal University Computer Center ___ oi-dev mailing list oi-dev@openindiana.org http://openindiana.org/mailman/listinfo/oi-dev
Re: [oi-dev] OpenIndiana Docs (proof of concept) - What is it all about?
On 05/ 6/16 03:51 PM, Aurélien Larcher wrote: You need to understand WHY you support some actual project, possibly using it and wanting to have sucsess because you NEED it to work out. Not just some side-hobby because it is good place to spend your time without personal involvement part. So think again about your motivation and get back when you have something more positive to say about OI. Please stay on-topic: technical feedback on a demonstration. It is on topic as much as previous message is on topic. It is you who are talking to me personally instead of saying something about issues I pointed out.. Get back and try to actually answer to my post instead of talking to me.. This idea of yours is a cancer and you are just reading a cure for it. Also if you base your "inclusion" in "excluding" people as a main tool, you surely are _not_ a material for any type of human and project management in OI. Same applies here, your attitude is dismissive and you do not provide input regarding the technical merits or shortcomings of the proposal. This is technical issue that converting docs should be done within Openindiana project with tools we have and not outside of it. The matter has been discussed several times, including on IRC with you. No you are not telling the truth as i know of it. If you discussed something privately with Michael, that is not what is publicly known, before you started with extracting Handbook out of Openindiana. This is a discussion, let us remain open and courteous and let us get back to the topics: technical benefits + contribution process. Please, you are not responding to anything I said but you are trolling me personally. Please use your own medicine and for a change respond to issues I posted before. I can't repeat myself because you refuse to read. ___ oi-dev mailing list oi-dev@openindiana.org http://openindiana.org/mailman/listinfo/oi-dev
Re: [oi-dev] OpenIndiana Docs (proof of concept) - What is it all about?
> > You need to understand WHY you support some actual project, possibly using > it and wanting to have sucsess because you NEED it to work out. Not just > some side-hobby because it is good place to spend your time without > personal involvement part. > So think again about your motivation and get back when you have something > more positive to say about OI. > Please stay on-topic: technical feedback on a demonstration. > Coming from isolated environment, you misplace open reactions and idea and > project building for hostility. Actually, ANY request for actual hostility > creation toward individuals , that you recommend as a way of doing things > must be squashed instantly. > Trolling this project with "exclusion" of people as way of doing things > will not be accepted. > ANYONE asking for any other person to be disgarded should be disgarded > itself so that such unfriendly and inhumane requests you propose don't tore > this community apart. > > This idea of yours is a cancer and you are just reading a cure for it. > Also if you base your "inclusion" in "excluding" people as a main tool, > you surely are _not_ a material for any type of human and project > management in OI. > Same applies here, your attitude is dismissive and you do not provide input regarding the technical merits or shortcomings of the proposal. > > This is all already solved by Openindiana Wiki. > http://wiki.openindiana.org/oi/OpenIndiana+Wiki+Home > Acually illumos even turned it's main page to wiki, to have less BS to be > worried about. > > Surely this is not true and Openindiana is documented through Wiki and > Opensolaris docs that need renewal, > while large part of Openindiana functionality is mutual with illumos, too. > Opensolaris docs are very large and very well written and there is not > many project on internet with so many good docs like OI, you just choose > not to see it. > So this is not positive assertion at all toward the project nor reflects > real state of things. > > This is also false statement. > One with a positive attitude tend to improve, not replace with something > newer and wit less merit. > You surely should spend more time on it and TALK to people about improving > it, before jumping conclusions. > This you personal opinion only and the points listed by Michael are objectively not completely addressed by the Wiki. The matter has been discussed several times, including on IRC with you. You have the right to disagree but please do not make generalities. Instead of leaving the discussion getting out off hand and having to reconnect pieces scattered across several emails, may I suggest that you formalize your take on documentation ? Please do it in a reasonable time frame so that we can keep the momentum of Michael's initiative. I am personally very positive about the proposed system as it solves several shortcomings of the existing one. If not better proposition is voiced and *implemented* I do not see why the idea cannot move forward. If criticism does not lead to a better solution and offers no implementation, one cannot justify not moving forward. This is a discussion, let us remain open and courteous and let us get back to the topics: technical benefits + contribution process. ___ oi-dev mailing list oi-dev@openindiana.org http://openindiana.org/mailman/listinfo/oi-dev
Re: [oi-dev] OpenIndiana Docs (proof of concept) - What is it all about?
On 05/ 4/16 07:00 AM, Michael Kruger wrote: * Community conduct * Project visibility * Proof of concepts * Version control * Hosting infrastructure * Project marketing, SEO * Existing docs (OSOL Docs) * Viability/Usability of Wiki * dlc.openindiana.org/docs * Documentation Standards (media types, etc.) * Licensing/Contributer agreements/copyrights, branding etc. As I see you haven't start talking on any of this topics. Ah well. So, this is my creative outlet. This is a place where I can express myself, learn, try new things, and explore new ideas. It's a place where I can (hopefully) make a difference. So basically, you need a place to vent? i think OI community can recognize there is much more then this to be connected to OI. You need to understand WHY you support some actual project, possibly using it and wanting to have sucsess because you NEED it to work out. Not just some side-hobby because it is good place to spend your time without personal involvement part. So think again about your motivation and get back when you have something more positive to say about OI. If not, the project will eventually curl up and die. No it will not cur.. and it surely does not depend on you.. Are you injecting to us some feeling of bad taste? However, before any of that happens, people may find themselves needing to work alone or in small groups That way of working is not positive , all work needs to be public (therefore no submarines). Constant communicating plans, intentions and work has a positive way of having feedback that can correct you in early stages and make it better. So we should not support constantly including new submarines as a process. You should as frequently and to many people: "what do you think?", "have any idea?" and not thinking you always (or ever) having the best one. So accepting other peoples' reactions an guidance is crucial if you don't want to go underwater. specifically and intentionally excluding individuals with problematic behaviors. This will occur because it's simply not possible to get anything done in an atmosphere of hostility, jumping to premature conclusions, or where kvetching is the rule of the day. Coming from isolated environment, you misplace open reactions and idea and project building for hostility. Actually, ANY request for actual hostility creation toward individuals , that you recommend as a way of doing things must be squashed instantly. Trolling this project with "exclusion" of people as way of doing things will not be accepted. ANYONE asking for any other person to be disgarded should be disgarded itself so that such unfriendly and inhumane requests you propose don't tore this community apart. This idea of yours is a cancer and you are just reading a cure for it. Also if you base your "inclusion" in "excluding" people as a main tool, you surely are _not_ a material for any type of human and project management in OI. This leads me to suggest there should be an OpenIndiana 'Code of Conduct' to help reign in people with troublesome behaviors. After all, such individuals effectively prevent others from achieving anything meaningful. The future of the project may very well depend on it. You just broke unofficial existing Code of conduct, that is not calling people themselves "kvetching" and bad names and therefore lowering discussions to off-topic and personal attacks. Presenting my comments above I see you are not understanding how things are done openly, I suggest you don't get yourself into any type of creating Codes of conduct, especially not for OI. Doing things openly - it is normal to have reactions and having them is exactly what IS positive. And it is not normal to replicate closed, isolated and excluding environment that you are maybe used to. I wrote it all for the pure joy of writing. And in the spirit of community, it's free and available to all. As said, you got to work on your motivations, but that's again, your personal thing and not putting personal things is a good way not to be ditched in off-topic. 1) Place documentation under distributed version control. 2) Lower the bar of entry to the documentation process. 3) Make changes and quickly deploy those changes in some kind of automated fashion (e.g. continuous integration). 4) Present the documentation in an organized and aesthetically pleasing way. This is all already solved by Openindiana Wiki. http://wiki.openindiana.org/oi/OpenIndiana+Wiki+Home Acually illumos even turned it's main page to wiki, to have less BS to be worried about. It's been said that a project lives or dies by it's documentation. Whether that's really true or not, I don't know, but the general perception for OpenIndiana is it's largely an undocumented project. Surely this is not true and Openindiana is documented through Wiki and Opensolaris docs that need renewal, while large part of Openindiana functionality is mutual with illumos,
Re: [oi-dev] OpenIndiana Docs (proof of concept) - What is it all about?
Hullo, Thank you Michael for this very well written and nuanced message, it surely gives more context to your proposal. As I am an early follower of your reflexions on documentation and we had the opportunity to exchange ideas, my reaction to your proposal can only be positive. > Having said all of that, let me turn the discussion back to my little docs > website proof of concept. For starters, it's not a submarine project, nor > do I intend to apply any kind of licensing which may restrict it's reuse in > any way. Frankly I could care less how it's licensed. I wrote it all for > the pure joy of writing. And in the spirit of community, it's free and > available to all. > Straight to the point, I should mention that several discussions by email and on #oi-documentation were preliminary to your initiative -- to gather context and input -- which hopefully contributed to your reflexion. > As for how it evolved the way it did, there are a number of reasons. > > As soon as I joined the project I began looking at the OSOL docs, the > website, and the wiki, and took notes of my thoughts and observations along > the way. Those notes are publicly available for anyone to see: > > https://github.com/makruger/openindiana-docs > > The README describes what's in each document. This is all public and has > been for quite some time. Again, not a submarine project at all. > > So, after looking at the current state of information management, several > things became clear. > > There needed to be a way to: > > 1) Place documentation under distributed version control. > 2) Lower the bar of entry to the documentation process. > 3) Make changes and quickly deploy those changes in some kind of automated > fashion (e.g. continuous integration). > 4) Present the documentation in an organized and aesthetically pleasing > way. > I cannot disagree with any of these points. In my successive research environments, documents were written exclusively in LaTeX for scientific documents + manuals for numerical libraries or a markup language for code-related notes, all of them under revision control system. Even applications for fundings or student thesis drafts are shared in a GIT repository and contributed to by collaborators with merge requests. My experience tells me that the argument against source files under revision control for documentation does not stand. > > It's been said that a project lives or dies by it's documentation. Whether > that's really true or not, I don't know, but the general perception for > OpenIndiana is it's largely an undocumented project. > One may argue that the reality is different but the point is that even if the documentation exists, the perception is more important because it may reflect the fact that: - part of the information is outdated making it difficult to distinguish what is applicable and what is not, - information is not visible or does not present a structure/hierarchy that makes it effectively usable, - interaction with the medium is flawed (impossibility to display), - content cannot be searched (impossibility to index). > > The need is there, now it's just a matter of coming up with a workable > method for addressing the need. Good docs are important. Just as important > is way the documentation is organized and presented. > > This leads me to state the obvious: > > The current state of the wiki is quite poor. The content is poorly > organized, largely outdated, and the navigation menus do not function at > all on mobile devices (this included tablets). This is a real problem, > especially if the project expects people to rely on the Wiki as the "go to" > source of information about the OpenIndiana project. > > I can only conclude by saying this is quite unacceptable and something > better is required. Whether that something better is my little project, or > something else entirely, that's for the community to decide. > I came to a similar conclusions when I started contributing to OI and I also think that having a collection of source files written in markup format allows generation to other formats and media than deployment to a website, e.g. generation of a PDF of the Handbook that can been readily shipped with the distribution together with a static HTML version. > > My proposal is on the table and I can only expect it to be fairly judged > on it's technical merits. It should not however be frontally assaulted > because it differs from the way things have always been done. > I would also highlight the fact that being a technological demonstration, any other concern is orthogonal to the current proposal and as such, while being pertinent for an hypothetical final implementation, should be considered in a next stage. We all liked the OpenSolaris books but they are not tractable by such a small community and the Wiki has too many technical shortcomings for end-user documentation. As I mentioned to several people, I see this initiative as the documentation counterpart to
Re: [oi-dev] OpenIndiana Docs (proof of concept) - What is it all about?
Hi Michael First of thank you for your hard work on the Documentation thus far. On 04.05.2016 07:00, Michael Kruger wrote: This leads me to suggest there should be an OpenIndiana 'Code of Conduct' to help reign in people with troublesome behaviors Here i would like to input a bit of my experiece as a Kaopilot Student. Kaospilots is a Business shool which works with community based organization models and frameworks. Thus we also study communities in a great detail. Ranging from 3500 Year old traditions to modern day Communities. What I have learned from that, is that if you "reign in people with troublesome behaviours" you will only cause more hostility. The best cause of action I find is to make people aware what their bevahiour causes. This gives those people the freedom to rethink their actions and handle how they see fit. This also happened in this case. And that person rephrased their mail to be more objective. If we want to write down some general rules about what we would like people to do when bringing critique about work done is another topic. But what i have learned in the 7 months working in this way is, it is hard to give objective and nice formulated feedback if you have not trained it. So whatever we write down. It does not work if people do not commit to it. 1) Place documentation under distributed version control. 2) Lower the bar of entry to the documentation process. 3) Make changes and quickly deploy those changes in some kind of automated fashion (e.g. continuous integration). 4) Present the documentation in an organized and aesthetically pleasing way. The current state of the wiki is quite poor. The content is poorly organized, largely outdated, and the navigation menus do not function at all on mobile devices (this included tablets). This is a real problem, especially if the project expects people to rely on the Wiki as the "go to" source of information about the OpenIndiana project. Please make people aware of this as soon as you see it. I was not aware of how the wiki behaves on tablet devices. Also you have a view of things that lang time project memebers do not have. We would realy like to see your view. Your view is a resource to reach more people with similar views on documentation. Thank you for sharing your View. I can only conclude by saying this is quite unacceptable and something better is required. Whether that something better is my little project, or something else entirely, that's for the community to decide. My proposal is on the table and I can only expect it to be fairly judged on it's technical merits. It should not however be frontally assaulted because it differs from the way things have always been done. On this point i agree. I would like to aks the people from the community to share what they think is a documentation. Or what they think a documentation requires. And what they want to be the outcome of this documentation project. Greetings Till ___ oi-dev mailing list oi-dev@openindiana.org http://openindiana.org/mailman/listinfo/oi-dev
