Debian for the first day administrator.
Hello,
First thing:
Thanks to everyone that has contributed in the time and to everyone
contributing to improve the Debian documentation.
Second thing,
I've mentioned previously in 2 times to people directly involved in
Debian, on public conversation, the possibility to have a better
Debian specific docs for the final user. Like perform a Debian
vanilla install and run: man -k debian.
If you're a Debian user with many years doing it... think how many
things you have learn from debian documentation, and how many you have
learn by news, mails, blogs, forums, irc, people, etc...
¿we want to make our user free, right? if you've worked in I.T.
world, you know that knowledge and documentation are two weapons
against freedom.
All Debian NMs and DDs, translators and people managing the
infrastructure are doing a great job. Debian is a BIG development
TEAM. A team building an operative system.
Maybe it's just about improving something that already exist and I
don't know.
I think (fell free to correct or comment), that the Debian
documentation should:
- Being available as package when it's not a "dinamic" information
- Being available as HTML as weell as man page and txt where posible
- Mantain a "style" that match other Debian HTML data
(*.debian.org, etc) in such HTML
- Mantain the posibility to browse it online (?) (browse
includes having a clear to such documents)
- Being available in other formats (i.e. PDF compatible with the
most PDF readers possible) usually the formats that supports the tool
used to generate the two previous formats.
- Being easy to translate
- Needs to track at least the stable branch
- Needs to track whats happening with technology and the world
And sort after my thinking... some questions come to my mind as a
Debian final user, not NM, not DD, not translator:
How many of the currently available Debian documents need love to
match my points ?
How many of the tools being used, need love to ease contributions
of a final user (or even to ease the contribution of experienced NM,
DD or translators) ?
How many tools could be written to automate human steps or to ease
human work? anyone have some tool idea that does not implement by lack
of time?
What kind of work, code, documents, or investigation is needed or
welcomed in the Debian Documentation project nowdays?
Maybe some tool that does:
- websites and documents and translations are a single tree of source.
- tree of source, is parsed, and produces the output
- tree of source, has git submodules, so some sources can be .po
files, some sources can be markdown files, some sources can be
templates for html, and they are parsed to produce the output
(websites, documents and translations" depending of submodule.
I don't know it it' s worse on how it's done now, but I do not see
it hard to write, and a modular arch could help to reuse CSS work,
extend the tree with new parser plugins, like a bugktrack client or a
wiki client that adds information to documents at releasing time, a
podcast station for disabled users, reading Debian documents every the
day, etc...
plugins are indeed needed, so one can plug debian-foo documents and
profuce unified output.
If I were a Debian developer, I wouldn't like the FIRST WEEK user
being jumping accross styled and unstyled HTML, choosing accross
unrelated and unknown paths, and having to "read 500 pages" to get
introduced on what you can retain of those 500 pages that you're going
to learn failing, breaking, learning tricks, new undocumented things,
not so accessible docs, or even looking sometimes at code.
Debian documents have to talk only about install and configure
packages? can we have documents about software freedom in 2012? about
user tracking without knowledge? what about to teach to distribute job
across such recycled computers to solve social problems, etc?
Time ago I attached this draft of "man Debian" in POD format, to a
flame in debian-devel, I reattach in this message to debian-doc.
Re-reading it, it lacks a "man afterboot" or "man quickstart" to
introduce the user to the default daemons (cron, rsyslog, mta, etc),
default shells, etc Of course it's a draft idea. I think the right
direction may pass by unify such index of information, with the web
site navigation that the Debian final user gets.
=head1 NAME
Debian - The universal operative system.
=head1 SYNOPSIS
Debian is a free operating system (OS) for your computer. An OS is the set
of basic programs and utilities that make your computer run.
=head1 DESCRIPTION
Debian GNU/Linux uses the Linux kernel (the core of an OS), but most of
the basic OS tools come from GNU project; hence the name GNU/Linux.
Debian GNU/Kfreebsd uses the FreeBSD kernel, but most of the OS tools
come from GNU project; hence the name GNU/FreeBSD.
Debian provides more than a pure OS: it comes with over XX000 packages,
precompiled software bundled up in a nice format, for easy installation on
your machine.
=head1 GETTING STARTED
You are using a program called B<man> that program has its own manual, and
also talks about how you can search into the documentation and more topics.
To open the B<man> manual you will need:
man man
Debian documentation is very extensive and detailed. This manual comes in
each Debian release, and index which directions you can choose:
B<General>
man man
man debian
man debian_help_and_contact
man debian_squeeze
man debian_squeeze_upgrade
man debian_releases
man debian_bugs
B<Debian Project>
man debian_free_software
man debian_social_contract
man debian_help_and_contact
man debian_donations
man debian_mailing_lists
man debian_news
man debian_partners
B<Debian Development>
man debian_developer
man debian_documentation
man debian_mantainer
man debian_teams
man debian_translation
B<Debian OS>
man debian_system_boot
man debian_sysyem_kernel
man debian_system_init
man debian_system_networking
man debian_system_software
man debian_system_policies
B<Other>
man_debian_history
man_debian_fooo
man debian_reference
=head1 ONLINE INFORMATION
B<General>
Lhttp://www.debian.org
Lhttp://www.debian.org/...
Lhttp://www.debian.org/...
Lhttp://.....debian.org/
L...
Reply to: