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