> Date: Sun, 1 May 2016 00:30:55 -0400 > From: Michael Kruger <makruger2...@gmail.com> > To: OpenIndiana Developer mailing list <oi-dev@openindiana.org>, > Discussion list for OpenIndiana <openindiana-disc...@openindiana.org> > Subject: [oi-dev] demonstration docs website > Message-ID: <5725867f.9030...@gmail.com> > Content-Type: text/plain; charset=utf-8; format=flowed > > Hello all, > > Here is a little something I have been working to help showcase > documentation for the OpenIndiana project. > > Currently hosted are: > > OpenIndiana FAQ (Complete, but still growing and improving) > OpenIndiana Handbook (little more than a template at this point) > OpenSolaris Books (41 titles from the 2009 redistributable docs release) > > All of this resides on github, so further evolution of this website and > it's content simply follows existing development practices. > > Here is the URL: http://makruger.github.io/website/ > > Enjoy, > > Michael >
I am starting from the first email because there have been so many replies and responses to this one and no one has provided anything but it seems negative feedback to this git site. I also see very little contribution to the subject of documentation. Right now a majority of OpenIndiana docs are on the wiki here: http://wiki.openindiana.org/oi/OpenIndiana+Wiki+Home I have never even heard of http://dlc.openindiana.org/docs/ until it was mentioned a few days ago. I like wiki's. Personally I use archlinux and they have one of the best wiki's I have ever used. I like wikis because they are so dynamic. It is easy for me to edit, easy for me to fix. 1) Place documentation under distributed version control. Not all documentation I think should be under version control. Though, documentation created by the people that help create OI I think would. I really think that what you are creating is not a documentation site but a new handbook. Is there a public, updatable, handbook right now? I would keep the wiki AND have this nice handbook. I really think the front facing page should be integrated somewhere branching off of the main site to summarize the entirety of the OI documentation structure. It seems like, with the wiki and handbook approach, you would be duplicating work but then lets take a look at this page: http://wiki.openindiana.org/pages/viewpage.action?pageId=4883847 That page needs updated, it looks like 4k problem has been fixed, or possibly not. Why are people commenting instead of fixing the wiki itself? If you have a handbook that developers can edit simply and quickly once a problem has been fixed in OI, is this not better? Or is this a problem solved by man pages? 2) Lower the bar of entry to the documentation process. I do not know why the bar is high right now? Can you explain this more? Making an account on the wiki is not hard. Making an account on git is not hard either but I would like to mention that most people are used to editing wikis. 3) Make changes and quickly deploy those changes in some kind of automated fashion (e.g. continuous integration). Once again, I already talked about developer -> git docs editing, but can you please explain this more? Wikis are just click and edit. 4) Present the documentation in an organized and aesthetically pleasing way. https://makruger.github.io/website/pages/docs/handbook.html does not work. https is broken in your css. I agree a bit on this. I do not like Confluence, but it does make for a nice looking index layout. I am really a fan of mediawiki and I do not understand why they chose to go with the Atlassian Confluence Community License when mediawiki is FOSS. To each there own and I am sure it was thought about. I like straightforward layouts that do not obfuscate things. I want all the information on one page....not a million different menus. One large TOC/index and all the text at my fingertips. i should not need a search engine to search a manual. If I open up a handbook, I want the handbook. Though, if what you have created were to be accepted, you are adding more work. I do not OI has a dev lead or team right now right? Who is going to support it? The support/work might not be in vain though because documentation should support the release. It is very frustrating for users to use an OS and not find the docs they need. Or find out dated docs. Do you think a developer would take time to fix docs though when they already have man pages and README's? If you were to link the docs via github to code changes, every release could have its handbook frozen in time/git releases/names for each release. In fact I think this could be a powerful feature if OI ever does an LTS release. _______________________________________________ oi-dev mailing list oi-dev@openindiana.org http://openindiana.org/mailman/listinfo/oi-dev