On Fri, May 6, 2016 at 8:06 PM, WebDawg <[email protected]> wrote: > > Date: Sun, 1 May 2016 00:30:55 -0400 > > From: Michael Kruger <[email protected]> > > To: OpenIndiana Developer mailing list <[email protected]>, > > Discussion list for OpenIndiana < > [email protected]> > > Subject: [oi-dev] demonstration docs website > > Message-ID: <[email protected]> > > 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. >
Actually the bottom-line is: I trust what I can grep and sed. ;) > > _______________________________________________ > oi-dev mailing list > [email protected] > http://openindiana.org/mailman/listinfo/oi-dev > -- --- Praise the Caffeine embeddings
_______________________________________________ oi-dev mailing list [email protected] http://openindiana.org/mailman/listinfo/oi-dev
