[oi-dev] demonstration docs website

[WebDawg]

> 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.