[oi-dev] demonstration docs website

Fri May 6 18:27:37 UTC 2016

On Fri, May 6, 2016 at 8:06 PM, WebDawg <webdawg at gmail.com> wrote:

> > Date: Sun, 1 May 2016 00:30:55 -0400
> > From: Michael Kruger <makruger2000 at gmail.com>
> > To: OpenIndiana Developer mailing list <oi-dev at openindiana.org>,
> >         Discussion list for OpenIndiana <
> openindiana-discuss at openindiana.org>
> > Subject: [oi-dev] demonstration docs website
> > Message-ID: <5725867F.9030102 at 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.
>

Actually the bottom-line is: I trust what I can grep and sed. ;)

>
> _______________________________________________
> oi-dev mailing list
> oi-dev at openindiana.org
> http://openindiana.org/mailman/listinfo/oi-dev
>

-- 
---
Praise the Caffeine embeddings
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://openindiana.org/pipermail/oi-dev/attachments/20160506/ae3bb91f/attachment-0005.html>