kubuntu ubuntuguide version

[Abdullah Ramazanoglu]

Sean Wheller dedi ki:
  --8<--

> Abdullah,
> 
> Thanks for you input.

And thank you for your kind help, too, both in your mail reply and here.

> While I admit there is a barrier to entry for authors to contribute
> documentation, I would just like to address some of the points you would
> like to see. Before I do, just let me say that I am currently evaluating
> Apache Lenya to address the barriers you mentioned. You may want to take
> a look. http://lenya.apache.org

It looks very nice really. I think some means of porting automation between
docbook and other formats might be equally helpful as well. As I have no
idea on difficulties of porting, I might be way off base here.

BTW, I would like to clarify a couple of points in my previous post.
Firstly, although I'm not familiar yet with docbook details, I'm fully
aware of its tactical importance and I have no questions at all wrt using
doocbook as the base format. Secondly, looking at it again, my previous
post really looks like a whining even to me. But I really didn't mean it
that way. I was trying to address an issue in greater context, taking
myself completely out of the picture. Honest. :)

I was presuming that *if* porting procedures can be somewhat automated, and
if well defined rules can be established to facilitate automated back and
forth conversions, then it might be made into something more or less
similar to deb packaging process. Further building on that presumption, I
was imagining authorship and packaging might be separated into two
independent, detached roles. Thus, a relatively very small documentation
team might be able to herd a large number of authors, and more
importantly, there would be large number of willing authors as they become
able to write in whatever format they find convenient. Additionally, any
random document out there found valuable for K/ubuntu could be easily
adopted. Thus, all of a sudden vast documentation resources could become
available.

It was just a presumption, maybe wishful thinking, without a factual
backing. In the future, as I learn more about docbook details, I hope I do
more informed suggestions. :)

As for me, I guess I need to do something first, before getting motivated
into converting it into something better - docbook. Otherwise (in my case)
spending too much time with non-essentials may absorb the initial momentum
needed for nucleating the essential.

Also I've several competing ideas. One of them is what I mentioned in my
mail: Something along the lines of Ubuntuguide (maybe later on doing some
scripting to automate some of the tasks in the doc). This is pure
documenting work at the beginning. Another idea is doing the scripting as
the main work, and preparing documentation as centered around the script:
As each functionality goes into the script, related context sensitive help
and program manual section gets written. In this case I've no idea how I
can stick to a consistent document structure. Maybe it's better to start
out with document skeleton preparation as in the former case, fill the
empty slots in the doc via the latter method, and after the script is
finished, fill the remaining empty slots in the doc again as in the former
case. I hope I'll decide before Breezy! :)

  --8<--
> Abdullah, we have helped a number of authors join the team and become
> productive with SVN and Docbook. These people have had an interest in
> learning and we understand that they do not know everything. Our approach
> is to mentor and support these people. As I say, we have been very
> successful in this respect and perhaps we can help you.

Are there resources (docs, tools, anything) for porting between docbook and
other formats? Or does it need to be done manually?

> The important message here, often not understood, is that the
> documentation sources and the process for development extends way beyond
> the initial first revision of a document and beyond just viewing it on a
> web site. In addition, I think that people need to appreciate that our
> documentation effort in SVN and Docbook is still very young, less than a
> year.

I agree. Yet I have a feeling that there might be two approaches to
documentation. One is author=publisher (I liken it to software
developer=packager), the other is author=author and publisher=publisher
(as in printed publishing and deb packaging). I still can't get rid of the
hopes that if only these two roles could be separated in a well defined
procedural way, then we could have more docs than we cared for.

> Hope this helps.

Definitely. Thank you very much!

Best regards :)
-- 
Abdullah Ramazanoglu
aramazan ÄT myrealbox D0T cöm