<div dir="ltr"><div><div>Hullo,<br></div>Thank you Michael for this very well written and nuanced message, it surely gives more context to your proposal.<br></div>As I am an early follower of your reflexions on documentation and we had the opportunity to exchange ideas, my reaction to your proposal can only be positive.<br><br><div><div><div><div class="gmail_extra"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
Having said all of that, let me turn the discussion back to my little docs website proof of concept. For starters, it's not a submarine project, nor do I intend to apply any kind of licensing which may restrict it's reuse in any way. Frankly I could care less how it's licensed. I wrote it all for the pure joy of writing. And in the spirit of community, it's free and available to all.<br></blockquote><div><br></div><div>Straight to the point, I should mention that several discussions by email and on #oi-documentation were preliminary to your initiative -- to gather context and input -- which hopefully contributed to your reflexion.<br><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
As for how it evolved the way it did, there are a number of reasons.<br>
<br>
As soon as I joined the project I began looking at the OSOL docs, the website, and the wiki, and took notes of my thoughts and observations along the way. Those notes are publicly available for anyone to see:<br>
<br>
<a href="https://github.com/makruger/openindiana-docs" rel="noreferrer" target="_blank">https://github.com/makruger/openindiana-docs</a><br>
<br>
The README describes what's in each document. This is all public and has been for quite some time. Again, not a submarine project at all.<br>
<br>
So, after looking at the current state of information management, several things became clear.<br>
<br>
There needed to be a way to:<br>
<br>
1) Place documentation under distributed version control.<br>
2) Lower the bar of entry to the documentation process.<br>
3) Make changes and quickly deploy those changes in some kind of automated fashion (e.g. continuous integration).<br>
4) Present the documentation in an organized and aesthetically pleasing way.<br></blockquote><div><br></div><div>I cannot disagree with any of these points.<br><br></div><div>In my successive research environments, documents were written exclusively in LaTeX for scientific documents + manuals for numerical libraries or a markup language for code-related notes, all of them under revision control system.<br></div><div>Even applications for fundings or student thesis drafts are shared in a GIT repository and contributed to by collaborators with merge requests.<br></div><div>My experience tells me that the argument against source files under revision control for documentation does not stand.<br> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
It's been said that a project lives or dies by it's documentation. Whether that's really true or not, I don't know, but the general perception for OpenIndiana is it's largely an undocumented project.<br></blockquote><div><br></div><div>One may argue that the reality is different but the point is that even if the documentation exists, the perception is more important because it may reflect the fact that:<br><br></div><div>- part of the information is outdated making it difficult to distinguish what is applicable and what is not,<br></div><div>- information is not visible or does not present a structure/hierarchy that makes it effectively usable,<br></div><div>- interaction with the medium is flawed (impossibility to display),<br>- content cannot be searched (impossibility to index).</div><div> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
The need is there, now it's just a matter of coming up with a workable method for addressing the need. Good docs are important. Just as important is way the documentation is organized and presented.<br>
<br>
This leads me to state the obvious:<br>
<br>
The current state of the wiki is quite poor. The content is poorly organized, largely outdated, and the navigation menus do not function at all on mobile devices (this included tablets). This is a real problem, especially if the project expects people to rely on the Wiki as the "go to" source of information about the OpenIndiana project.<br>
<br>
I can only conclude by saying this is quite unacceptable and something better is required. Whether that something better is my little project, or something else entirely, that's for the community to decide.<br></blockquote><div><br></div><div>I came to a similar conclusions when I started contributing to OI and I also think that having a collection of source files written in markup format allows generation to other formats and media than deployment to a website, e.g. generation of a PDF of the Handbook that can been readily shipped with the distribution together with a static HTML version.<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
My proposal is on the table and I can only expect it to be fairly judged on it's technical merits. It should not however be frontally assaulted because it differs from the way things have always been done.<br></blockquote><div><br></div><div>I would also highlight the fact that being a technological demonstration, any other concern is orthogonal to the current proposal and as such, while being pertinent for an hypothetical final implementation, should be considered in a next stage.<br><br></div><div>We all liked the OpenSolaris books but they are not tractable by such a small community and the Wiki has too many technical shortcomings for end-user documentation.<br><br>As I mentioned to several people, I see this initiative as the documentation counterpart to oi-userland and should be the opportunity for a documentation reboot.<br></div><div>Of course ephemeral documentation and developer-centric notes should stay on the Wiki and it may be used as a sandbox but final user documentation should be addressed within a system as defined by Michael.<br><br></div><div>Several points are to be discussed but I will stop here to keep this message fairly general and concise.<br><br></div><div>Thank you Michael for your well-structured proposal as well as the analysis attached to it.<br><br></div><div>Aurelien<br></div><div><br></div><div><br> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
Michael<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
<br>
_______________________________________________<br>
oi-dev mailing list<br>
<a href="mailto:oi-dev@openindiana.org" target="_blank">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>
</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></div></div></div>