discuss: Thread: Linux Documentation needs much work and ideas

When I revised the Manifesto I added a new task for LDP: to devise a
better system for linux documentation (and not just LDP documentation).
Years ago there was a lot of discussion on this topic but no conclusions
or consensus was reached.  This discussion has been long since
forgotten.  And the problem hasn't been solved.  In fact it may have
gotten worse since each Distribution is trying to do it's own
documentation with little available good docs from LDP to make it
easier.

One can use search engines to hunt for docs but it's not easy since
there is so much stale documentation on the Internet, including a lot
from old LDP docs.  Some non-LDP docs are not even dated.  A person
looking for help often will not even realize that the documentation is
out-of-date until they start trying to follow thru with it.  Another
problem is that most LDP docs assume that the reader already knows a
fair amount about the topic and there isn't much that appeals to someone
who uses mainly a point-and-click interface and doesn't understand much
about so called "computer science".

On the desktop, Linux still doesn't have much more market share than it
did 10 years ago, and better documentation would help increase it's
market share.  If it presented the details of differences between
distributions, perhaps some of this material could be used in the task
of making the various distributions more standardized thus enabling
persons to readily switch from one distribution to another and
simplifying documentation.  Ideally, the same documentation could be
used for almost all distributions.

If LDP is not going to produce much documentation from here on, perhaps
it can try to host discussions on documentation.

			David Lawyer

I agree that documentation for Linux is spread out all over the web. The
main places documentation resides are Linux forums, individual
distribution's forums and wiki.

Personally I feel that forums, HOWTOS and guides, and wikis should not be
independent. *Wikis provide topical information at an introductory level*.
They provide sufficient information for troubleshooting, and preliminary
learning on a topic. When I was starting out, wikis were really helpful,
for example in topics such as keyboard and wireless. I especially love the
Arch Linux wiki because they are so comprehensive and clearly written.
Forums like linuxforums and distribution's forums provide help on more
specific problems faced by users, and also encourage sharing of code and
configuration. It is important because that is where a distribution's user
base interacts, where its community lives.
As for HOWTOs and guides, such as those on TLDP, they contain in-depth
knowledge. I personally find them very useful. But most people will not
probably get pass the first chapter (with reference to the market share of
Linux).

I was also reading through the discussion list, and picked up an important
point:
-The wiki is a "beta holding ground", for guides that were incomplete not
not ready to be published.
Personally I do not agree with this but if it was the original intent then
we probably need to hold some discussion.

As for the presentation of the front-page, I agree that there needs to be
work done. Aesthetics has gained much importance in recent years and the
way TLDP looks might have turned quite some people away. I'm not HTML CSS
wiz (and my design skills are worse), but I will try.

Sincerely,
Ng Zhi An

Wiki format is best.

>I was also reading through the discussion list, and picked up an important
>point:
>-The wiki is a "beta holding ground", for guides that were incomplete not
>not ready to be published.

True, but most Wiki's have an embedded publish button, allowing the viewer to 
print to a printer or export to PDF/PS or EPUB, or other desired format.

After awhile of editing, corrections and formatting corrections, the documents 
are usually better and more up-to-date then anything published in the past.

Else, you end-up with something like TLDP, where the documentation is full of 
errors and out-dated.  Caused by being next to impossible to submit corrections 
by the average viewer.  Like somebody experienced is going to take the time to
meticulously reread the documentation like an initial reader does.

Initially, didn't think worth while to respond as I just assumed people would 
already understand this.

If TLDP wants a finished product, have a script to automatically take snapshots 
of the Wiki pages, publishing to PS/PDF/HTML as they do now.

I don't think there's much argument as to what's best, just think energy for 
documentation is more focused at the Distro level, in an effort to gain 
advertisement and interest for their Distro.  The flip-side being, duplicated 
and replicated documentation efforts.

The majority of duplicated efforts, should probably be candidates for merging 
into TLDP, along with it's already acquired documentation.

Think Wiki and TLDP's lack of interest in Wiki is the primary move to 
documentation at the Distro level.

... just some thoughts.


--
Roger
http://rogerx.freeshell.org/

Over a year ago I suggested this idea and was shot down. I have missed
a lot of this conversation, what has changed?

V/R,

Paul Hendricksen

On Dec 24, 2012, at 9:05 AM, Roger ####@####.#### wrote:

> Wiki format is best.
>
>> I was also reading through the discussion list, and picked up an important
>> point:
>> -The wiki is a "beta holding ground", for guides that were incomplete not
>> not ready to be published.
>
> True, but most Wiki's have an embedded publish button, allowing the viewer to
> print to a printer or export to PDF/PS or EPUB, or other desired format.
>
> After awhile of editing, corrections and formatting corrections, the documents
> are usually better and more up-to-date then anything published in the past.
>
> Else, you end-up with something like TLDP, where the documentation is full of
> errors and out-dated.  Caused by being next to impossible to submit corrections
> by the average viewer.  Like somebody experienced is going to take the time to
> meticulously reread the documentation like an initial reader does.
>
> Initially, didn't think worth while to respond as I just assumed people would
> already understand this.
>
> If TLDP wants a finished product, have a script to automatically take snapshots
> of the Wiki pages, publishing to PS/PDF/HTML as they do now.
>
> I don't think there's much argument as to what's best, just think energy for
> documentation is more focused at the Distro level, in an effort to gain
> advertisement and interest for their Distro.  The flip-side being, duplicated
> and replicated documentation efforts.
>
> The majority of duplicated efforts, should probably be candidates for merging
> into TLDP, along with it's already acquired documentation.
>
> Think Wiki and TLDP's lack of interest in Wiki is the primary move to
> documentation at the Distro level.
>
> ... just some thoughts.
>
>
> --
> Roger
> http://rogerx.freeshell.org/
>
> ______________________
> http://lists.tldp.org/
>

> On Mon, Dec 24, 2012 at 10:18:09AM -0700, Paul Hendricksen wrote:
>Over a year ago I suggested this idea and was shot down. I have missed
>a lot of this conversation, what has changed?
>
>V/R,
>
>Paul Hendricksen

Probably nothing. LOL.

Stuff takes time and energy to engineer, of which I've had little of these 
days.

--
Roger
http://rogerx.freeshell.org/

I'll set up a wiki and convert some documents.

V/R,

Paul Hendricksen

On Dec 24, 2012, at 10:35 AM, Roger ####@####.#### wrote:

>> On Mon, Dec 24, 2012 at 10:18:09AM -0700, Paul Hendricksen wrote:
>> Over a year ago I suggested this idea and was shot down. I have missed
>> a lot of this conversation, what has changed?
>>
>> V/R,
>>
>> Paul Hendricksen
>
> Probably nothing. LOL.
>
> Stuff takes time and energy to engineer, of which I've had little of these
> days.
>
> --
> Roger
> http://rogerx.freeshell.org/

On Mon, Dec 24, 2012 at 5:49 PM, Paul Hendricksen
####@####.#### wrote:
> I'll set up a wiki and convert some documents.

Wiki is already set up, http://wiki.tldp.org/

S.

Where's the delay then? We just need volunteers to convert documents?

V/R,

Paul Hendricksen

On Dec 24, 2012, at 10:53 AM, Sergiusz Pawlowicz
####@####.#### wrote:

> On Mon, Dec 24, 2012 at 5:49 PM, Paul Hendricksen
> ####@####.#### wrote:
>> I'll set up a wiki and convert some documents.
>
> Wiki is already set up, http://wiki.tldp.org/
>
> S.
>
> ______________________
> http://lists.tldp.org/
>

On Mon, Dec 24, 2012 at 5:55 PM, Paul Hendricksen
####@####.#### wrote:
> Where's the delay then? We just need volunteers to convert documents?

Yes, everything is related mostly to lack of skilled volunteers :-(

S.

On Mon, Dec 24, 2012 at 1:17 PM, Sergiusz Pawlowicz
####@####.#### wrote:
> On Mon, Dec 24, 2012 at 5:55 PM, Paul Hendricksen
> ####@####.#### wrote:
>> Where's the delay then? We just need volunteers to convert documents?
>
> Yes, everything is related mostly to lack of skilled volunteers :-(

If someone wants to set up a work queue where we can see the list of
all documents with the following fields:

* conversion status (TODO, in progress, done)
* source URI
* destination URI (where on the wiki)

That would probably help immensely. It'd operate as a checklist and a
good way to get all the content copied over and initially formatted.
Review and cleanup can follow.

Were there such a list, I'd be able to point people who follow Rosetta
Code at it, asking for volunteers.

--
:wq