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 > [email protected] > http://openindiana.org/mailman/listinfo/oi-dev > -- --- Praise the Caffeine embeddings
_______________________________________________ oi-dev mailing list [email protected] http://openindiana.org/mailman/listinfo/oi-dev
