[oi-dev] OpenIndiana Docs (proof of concept) - What is it all about?

Wed May 4 15:13:30 UTC 2016

Hullo,
Thank you Michael for this very well written and nuanced message, it surely
gives more context to your proposal.
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.

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

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.

> As for how it evolved the way it did, there are a number of reasons.
>
> 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:
>
> https://github.com/makruger/openindiana-docs
>
> 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.
>
> So, after looking at the current state of information management, several
> things became clear.
>
> There needed to be a way to:
>
> 1) Place documentation under distributed version control.
> 2) Lower the bar of entry to the documentation process.
> 3) Make changes and quickly deploy those changes in some kind of automated
> fashion (e.g. continuous integration).
> 4) Present the documentation in an organized and aesthetically pleasing
> way.
>

I cannot disagree with any of these points.

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.
Even applications for fundings or student thesis drafts are shared in a GIT
repository and contributed to by collaborators with merge requests.
My experience tells me that the argument against source files under
revision control for documentation does not stand.

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

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:

- part of the information is outdated making it difficult to distinguish
what is applicable and what is not,
- information is not visible or does not present a structure/hierarchy that
makes it effectively usable,
- interaction with the medium is flawed (impossibility to display),
- content cannot be searched (impossibility to index).

>
> 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.
>
> This leads me to state the obvious:
>
> 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.
>
> 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.
>

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.

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

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.

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.

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

Several points are to be discussed but I will stop here to keep this
message fairly general and concise.

Thank you Michael for your well-structured proposal as well as the analysis
attached to it.

Aurelien

>
> Michael
>
>
>
>
>
>
>
>
> _______________________________________________
> 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/20160504/d6c5b5b4/attachment-0005.html>