<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><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></blockquote><div><br></div><div>But I think with this example you are exactly pointing out the fact that documentation covers different things:<br></div><div>- developer notes<br></div><div>- ephemeral information (i.e workarounds)<br></div><div>- end user documentation (fairly static)<br></div><div>- etc...<br><br></div><div>So Wiki and Michael's proposal are complementary as they address different types of documentation and it was never the question to replace the Wiki.<br></div><div>The Wiki does not allow you to generate to different media as it would be required for the Handbook.<br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<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></blockquote><div><br></div><div>Ability to ask for review comes to my mind.<br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<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></blockquote><div><br></div><div>I would actually be more confortable editing source files and doing PRs.<br></div><div>In a math/physics research environment everything is written in LaTeX (also mark-up language for algo/code-related documents).<br></div><div>Even applications for fundings are shared in git and merged from different branches.<br><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<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>I think so too.<br> <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>