[illumos-Discuss] Documentation project

[Garrett D'Amore]

Um, we're working on it.  Unfortunately right now the process is unduly
painful, and we're focusing mostly on making it less painful than on
documenting the pain. ;-)

	- Garrett

On Thu, 2010-08-19 at 13:29 -0700, Ben Rockwood wrote:
> I definitely think a docs project is a good idea, however I think the
> first thing to produce is a really good developers guide.
> 
> I think they key to Illumos's success is making it all about the code. 
> In the Linux community building the kernel is something of "right of
> passage".  I would very much like it to be the same in the Illumos
> community.
> 
> So far I haven't seen any Illumos docs on the build process.  Can we
> gather up what we have an start working on a proper manual?
> 
> benr.
> 
> 
> On 8/19/10 11:58 AM, Garrett D'Amore wrote:
> > I think it *may* be too early to start formally documenting things.
> > I've been thinking about this too.
> >
> > We do need a handbook of sorts.
> >
> > We need man pages.  Right now we have none -- they are in a separate
> > consolidation.  Figuring out whether we keep them as such or integrate
> > them into the gate is a topic for reasonable debate. (I see multiple
> > possible directions, with various pros/cons.)
> >
> > I think right now the first thing to do is start improving the
> > documentation on the wiki.
> >
> > We also need to engage actual writers.  I know that there are some that
> > have expressed an interest in our community -- we will have to see what
> > happens.
> >
> > 	- Garrett
> >
> > On Thu, 2010-08-19 at 20:44 +0200, Antonio Vieiro wrote:
> >> Hi all,
> >>
> >> I noticed there's no documentation project yet, so I created one.
> >>
> >> The basic plan I propose is as follows:
> >>
> >> 1. Get a basic infrastructure for building the documentation, I'd like 
> >> to use DocBook 5, as it can generate HTML/PDF/ePub from a sinle source 
> >> and can be easily translated.
> >>
> >> 2. Start building a very first document, a handbook similar to 
> >> FreeBSD's. The very first contents should be how to set-up the a 
> >> development environment, build and install, etc.
> >>
> >> So what do you think? Is it too early to start documenting things? Any 
> >> comments on the project?
> >>
> >> Cheers,
> >> Antonio
> >>
> >>
> >>
> >> [1] http://www.freebsd.org/doc/en/books/handbook/
> >>
> >> _______________________________________________
> >> Discuss mailing list
> >> Discuss at lists.illumos.org
> >> http://lists.illumos.org/m/listinfo/discuss
> >>
> >
> >
> > _______________________________________________
> > Discuss mailing list
> > Discuss at lists.illumos.org
> > http://lists.illumos.org/m/listinfo/discuss
> 
> 
> _______________________________________________
> Discuss mailing list
> Discuss at lists.illumos.org
> http://lists.illumos.org/m/listinfo/discuss
>