[oi-dev] Fwd: [OpenIndiana-discuss] Documentation-Project

Mon May 30 14:11:27 UTC 2011

Tobias,

I was just discussing this with Deano on IRC...

My proposed litmus test is this: my girlfriend is willing to spend some time this summer helping out the project as a tech writer (she's got a background in speciality editing, although not as specialised as IT or *nix in particular). I'm pretty much with Garrett: the problem isn't that we using DocBook and should be using something else instead. If someone is interested in writing documentation, the question seems to be is there a mature toolset whose learning curve we can reduce to get someone willing able to be productive quickly. The issue is mostly one of front-end tools, and the question would thus be whether we can allow most editing to happen in a really simple format that can be marked up to DocBook for interchange, as a format that can be consumed by a PDF reader, a browser, or man. Alasdair's offered similar feedback recently. The DocBook people recognise as much: looking through some of the DocBook sites, I found the following remark:

"DocBook has the vices that go with its virtues. Some people find it unpleasantly heavyweight, and too verbose to be really comfortable as a composition format. That's OK; as long as the markup tools they like (things like asciidoc or Perl POD or GNU Texinfo) can generate DocBook out their back ends, we can all still get what we want. It doesn't matter whether or not everybody writes in DocBook — as long as it becomes the common document interchange format that everyone uses, we'll still get unified searchable documentation databases."[1]

The premise should be what simple format we can use to generate DocBook for what I'd take to be the very simple bulk of documentation tasks, preferably using a wiki-like editor. Doing some very brief research, I came up with Scroll Wiki Exporter, which would allow us to export documentation from the Confluence wikis we're already using for OI and Illumos.[2]

One way or another, the topic does seem ripe for discussion. If you're game to work with us through the decision process into implementation, how about we schedule you for a coming oi-meeting?

Cheers,
Bayard

[1] http://tldp.org/HOWTO/DocBook-Demystification-HOWTO/x57.html
[2] https://plugins.atlassian.com/plugin/details/7019

On 30 May 2011, at 05:24, Garrett D'Amore wrote:

> Switching to another less popular doc format doesn't seem like a great idea.  I don't work with the documentation frequently, but I'd ask people that do.
> 
> One thing is that some of these formats are like fads... they come and go.  I remember not long ago when SGML was all the rage. :-)  From my perspective it would be good to have a format that has good tools available (multiple implementations, at least some of which are portable to other platforms), displays nicely, and provides some basic structure capabitilities to assist in parsing for content or format conversion (e.g. to HTML).
> 
> If you make me install a bunch of new tools, or learn a format that nobody else uses, I probably will be less inclined to write documentation.  (That said, I've not written much except a few man pages, and the format of *those* is relatively constrained by the need to be able to display them with the man command. :-)
> 
>   -- Garrett D'Amore
> 
> On May 30, 2011, at 2:22 AM, "Tobias Famulla" <uni at famulla.eu> wrote:
> 
>> Dear all Developers,
>> 
>> As I mentioned on the Discussion-List(see below), I had the idea of transforming the OpenSolaris-documentation to another system and change some parts to the OpenIndiana specific behaviors.
>> 
>> Deano wrote on the Discussion-list, that it might be more helpful, to discuss the pros and cons of different systems and especially asking for people who also write the discussion and maintain it afterwards.
>> I think I am not able to maintain such documentation, because I am very new to the OpenIndiana and Solaris operating system and such developement process as a whole.
>> 
>> Because of that, I would ask on this list, if anybody sees the importance of an documentation, sees advantages of a special documentation system and would be able to maintain it. The other question is of course, whether the below described idea is an good one, or work on another part would be more helpful.
>> 
>> Sincerely,
>> 
>> Tobias
>> 
>> -------- Original-Nachricht --------
>> Betreff:	[OpenIndiana-discuss] Documentation-Project
>> Datum:	Thu, 26 May 2011 15:54:36 +0200
>> Von:	Tobias Famulla <ebay at famulla.eu>
>> Antwort an:	Discussion list for OpenIndiana <openindiana-discuss at openindiana.org>
>> An:	Discussion list for OpenIndiana <openindiana-discuss at openindiana.org>
>> 
>> Hello OpenIndiana-Community,
>> 
>> I am in an Open-Source-seminar at University, in which we have to hold a 
>> presentation about an Open-Source project and participate in the 
>> development-process of this project.
>> 
>> I chose OpenIndiana for this Course, because I think it is an 
>> interesting young project and the developement of a free Solaris is 
>> important for the open-source-community.
>> 
>> Becaus it lacks in a good documentation of OpenIndiana yet, as far as i 
>> read in the wiki, I had the idea of writing a script to transform the 
>> latest OpenSolaris documentation  from XML to a 
>> Sphinx-documentation(restructuredText) and rewrite it in some parts. I 
>> think Sphinx is a wonderful tool to write a good documentation and 
>> export it to html and pdf. It might be easier to handle these documents 
>> than the XML ones.
>> 
>> If you like the idea of writing the OpenSolaris-documentation in Sphinx, 
>> it might be helpful to integrate it in the revision control system to 
>> have an easy way to manage the documentation.
>> 
>> On another point, it would help me for the presentation, if someone 
>> writes me, how decisions for the project are made and how the project is 
>> managed(commitments to the sourcetree and something like that)
>> 
>> Sincerely yours,
>> 
>> Tobias Famulla
>> 
>> _______________________________________________
>> OpenIndiana-discuss mailing list
>> OpenIndiana-discuss at openindiana.org
>> http://openindiana.org/mailman/listinfo/openindiana-discuss
>> 
>> <uni.vcf>
>> _______________________________________________
>> oi-dev mailing list
>> oi-dev at openindiana.org
>> http://openindiana.org/mailman/listinfo/oi-dev
> _______________________________________________
> oi-dev mailing list
> oi-dev at openindiana.org
> http://openindiana.org/mailman/listinfo/oi-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://openindiana.org/pipermail/oi-dev/attachments/20110530/a61a22d4/attachment-0005.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 1515 bytes
Desc: not available
URL: <http://openindiana.org/pipermail/oi-dev/attachments/20110530/a61a22d4/attachment-0010.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: PGP.sig
Type: application/pgp-signature
Size: 841 bytes
Desc: This is a digitally signed message part
URL: <http://openindiana.org/pipermail/oi-dev/attachments/20110530/a61a22d4/attachment-0011.bin>