Rebirth of the Linux Documentation Project for Modern Use
 

Hello internet, I am just posting a quick little idea I had that you may be interested in.

I, like many (I would hope all) of you, am a GNU/Linux user. And during my quote-unquote 'linux journey' have found myself on The Linux Documentation Project website many a time. My visit typically consists of viewing a how-to of some sort. And every time it irks me that while likely thousands of people have viewed this very same page, it is still unstyled HTML. Not to mention many of these articles have not been updated for a decade (give or take). This is what we refer to as **The** Linux Document Project, and yet we choose to leave it in shambles. It is seemly a dead project, yet it still receives many visits annually.

So my idea here is to take a second look at what we have, and make an attempt at reviving this project for modern day use. My idea consists of a few things in this order:

1. Fork the existing LDP project hosted on GitHub, and convert it into a simpler format (I like to use the Asciidoc format since it is standardized unlike its more popular Markdown cousins. I have also been informed of texinfo which may be a possibility) for easier contribution/maintainence compared to raw Docbook.
2. Add a static site generator to the project (Again, my preference would be Middleman since it is extremely simple and can be extended easily)
3. Style the converted docs into something more pleasing to the eye (I find this especially important for new users). This will be quite simple using the static site generator mentioned above. But also retain thier ability to be distrobuted into other formats like .info and .txt for Linux devs who prefer those types.
4. Try our best to modernize these documents where needed (This will obviously be the hardest part). As to how this would be managed, I assume through Git, but any other ideas are welcome.

All in all, I think it is an achievable goal for a small group to convert the existing documets and get them up and running on a website and in a repo through Git. My only concern is overall interest in the Linux community. So here are a few questions for you readers to answer:

* Would you be interested in using such a site?
* Would you be willing to contribute (small or large) changes to such a site?
* Do you have any naming suggestions for such a project? :P

Thank you for your time, and please, if you're interesting, tell your friends! And please, if you have any criticism for my plan, feel free to share that too.

P.S., I am aware of the Linux Journey, but it irks me for a few reasons, including that it is not truly open source (only the markdown is available through a repo) and it attempts to brainwash new users occasionally. For example, on its kernel installation page it uses apt-get as *the* way to install a kernel. If find this extremely short-sighted to cite this as the only method. While it is far from the worst resource, I do not condone Linux Journey as a suitable guide to GNU/Linux as a whole.

EDIT 09/02/2016:

To anyone who is interested, I have created a Gitlab and Gitter for this project. You can use these to follow and contribute to the project in the future.

Gitlab repo: https://gitlab.com/lindoc/lindoc
Gitter group chat: https://gitter.im/lindoc/Lobby

Updating the format is one thing; updating the content would be a very big job.The most out-of-date sections are probably those that deal with hardware-related issues such as setting up sound. These would really have to be rewritten by experts.

I'd be happy to sign on as an editor.

priorities:

1) update tldp.org's content. no need to fork it, it already is a git project, hosted on github: https://github.com/tLDP/LDP - better contribute to that, no? don't reinvent the wheel.

and 2)... i couldn't care less for the looks of it. actually i prefer it that way: no javascript, pages load really fast, are viewable on any platform, require less server space, and, most of all, there's no fragile dependencies.

In reply to hazel:

I believe I am aware that there would be an extreme amount of work needed to make this a reality. My hope is that by making this an extremely community driven endevour, we could find people willing to do the more advanced technical portions, because I most certainly cannot do some myself.

And if I do got through with something like this, I would be willing to accept anyone I can get as an editor. But thank you for your early support!

In reply to ondoho:

Thank you for your feedback. I have a reddit thread running about this topic as well, and I have heard many share your sentiments about improving the documentation first, and I see the point in that. My only concern is that Docbook may not be the easiest form to maintain for A. The contributor and B. the maintainer(s) of the project.

As for contributing to the old project, while true in most cases, I feel dead documentation is an exception. There is a reason why TLDP is in the state that it is. This is why I feel it needs to be kickstarted as a new project of sorts.

And finally, my overall plan consists of keeping the underlying system 'modular' so to speak, so that we could serve a nicely formatted site and a 'style-less' version as well. I would also like to bring up the point that you do not need advanced or any javascript at all to create a nice looking website. If you don't know much about static site generators, you can read about them here. They provide websites that are much more efficient to the host server.

Style like this perhaps?

That's a lofty aspiration and I admire you for your even-ness in presenting your idea.
I like text.
It reminds me to RTFM and why I tell others to do so as well, but heck, spin up a new part/mount by hand.
I heads to tldp. I didn't come in scared.

/me bonks tmose1106 over the head with a 60 Lb. Unix Manual.

Yes, I was thinking something along the lines of the whole 'Previous, Next, Up, Home' scheme similar to that. The Linux from Scratch project is also a good source of inspiration. Just slightly more modern looking. But without all the crazy CSS libraries and things are out there today, just basic CSS styling. It could likely be done without any Javascript as well.

I think it is important for new users to have well made and somewhat visual pleasing documentation available. But we couldn't get too crazy with styling because as state above, some people would like just plain up-to-date HTML.

I would also be happy to assist as an editor or any other capacity in which I could help. TLDP has been a useful resource for me and I'd love to give back.

i still don't get it.
where's the point in forking the current tldp?
wouldn't it be better to start contributing along these guidelines?
and how is the LFS site better than tldp?
see the comparison in the attachments.
that's, like, 3 extra css rules for grey background on some elements, and duplicating the header on the bottom?
it also messes up in mobile view, which kind of proves my point from post #3

To answer your first three lines again, TLDP is a mess right now. And a great example is the page you led me to about their tasks and guidelines. Notice how under the 'immediate action items' it says 'As of September 2008...'. I honestly don't see how you can consider contributing to updating a project that can't even keep one of it's main web pages up to date for about 8 years. That indicates a mostly dead project if I have ever seen one. The point of this project would be to get it back into viewable and relevant state, and keep it that way.

To answer your issues with the CSS, just because I say, "take inspiration" does not mean I am going to exactly copy the also somewhat dated layout of LFS, though something based on the header there is a good thing to have for sorting through a guide-like document. And as your examples show, some TLDP guides already have such a thing incorporated. Though you are certainly correct that keeping mobile viewers in mind is very important.

If you would like to see some scalable work I have created before, you can check out the mock site I created for my Tad OS project. It is all HTML and CSS except for the header bar button which includes a tiny Javascript if statement. And while I am sure you can find a few spots where you can break it with a small screen size, I believe it works well on a very large majority of modern day devices. The resolution you are asking in your screenshots seems a little unrealistic in 2016, but I'm sure you are right that some people still use devices that size.

But just because CSS boxes are created does not mean they have to break everything. LFS was obviously not created for mobile, but at least it is up to date. And I'm sure if many people contribute, we could have a perfectly scalable site for 99% of situations.

And finally, as I stated previously twice, I would like to have a black and white, mostly CSS-lite option for people who like to view it that way to satisfy anyone like yourself who is against adding 'extra lines of CSS'.

point taken.
definitely taken; esp. when looking at the footer of said wiki page. 2008 per se is not bad, but "last edited 2011" is.


...aaaand the menu doesn't work without js enabled. my point precisely.



it's the default preset for the FF responsive design view.
there's something called virtual resolution (?) - i don't claim to understand it but it certainly exists, and is relevant even today. see here.

I'm glad we can see eye to eye on the state of TLDP :P

But just because I put a Javascript menu on the example I showed you does not mean I would like to use Javascript on the 'new LDP'. My point of my example there was more so scalability of pages. On another note, I have seen some hacks to create pure CSS menus like that using HTML checkboxes. Just for that webpage example, I felt it was a little out of my way. This is certainly something I will consider in the future though.

And thank you for the article there on virtual resolutions. Again, another important point that I should definetly keep in mind. Just overall I feel it is silly to worry about the CSS scaling when the project has not even begun XD But still, all good points and I would enjoy it if you could continue to provide such insight as the project progresses.

This thread reminds me of this thread.

I don't care much for the format of TLDP, and it is out of date for much of what I have looked for. It would be a lot of work to overhaul TLDP to bring everything up to date, but at the same time, I don't think we need yet another Linux documentation website.

I personally use Arch Linux's wiki for much of my online info not specific to Arch. The info is up to date and formatted nicely. It looks good in a terminal browser too minus the search function not working (at least in elinks).

What you bring up is mostly what I think is the problem with Linux documentation right now:

A. Any knowledgable user goes to ArchWiki. But note the description on ArchWiki's home page which says "your source for Arch Linux documentation on the web". Documenting things for literally every distro is very much out of the scope of 'Arch Linux documentation'. And all of these distros are simply documenting things over and over again, just repeating the same work over and over. TLDP is dedicated to doing things on Linux in general. The distros can document their specific things, but they should not put effort into documenting things that work on literally every single distro.

B. If you Google 'linux documentation', ArchWiki does not come up. The TLDP does. So as a new user, you go on TLDP, see it as outdated, and you leave dissappointed. Yet so many users, and I'm sure many new users come upon TLDP and feel let down every day. This is The Linux Documentation Project after all. And as you say, much of what you look for on the site is out of date. So one way or another, you find yourself on the site looking for information. It is a popular site, yet extremely outdated. This is why I feel it needs to be 'revived' so to speak. And things that are not relevent in 2016 can be taken out and replace with things that are.

But I want to know, what do you not like about TLDP's formatting? Is this in reference to how it is not as nicely formatted ArchWiki is? Because if so, I would love to make the TLDP more viewable in a terminal web browser. I feel that would be a boon to much of the Linux community. But I am also planning on releasing the 'reborn' TLDP on a daily basis in as many common formats as possible (styled HTML, non-styled HTML, manpages /etc), and even some more obscure cases such as Texinfo.

If you use Google to search 'linux documentation', the Arch Wiki does come up. The page number it shows up on will vary depending on your activity if you're logged-in to Google. Also, anyone not afraid to look past the first few results will come across other websites that do the same, such as linux.com and linux.die.net, among the many disto specific documentation. Most people new to Linux will most likely Google '<insert issue here>', instead of 'linux documentation'.

As far as the look, I find Arch's Wiki easier to navigate than TLDP, especially in a terminal.

While I do agree with your point about Google search result which I failed to recall, I can not understand how you cite linux.com and linux.die as alternatives. linux.com is filled articles and disordered lists of tutorials which show users how to install distros which likely have graphical UIs and how to install programs on Debian based systems. If anything, I call that useless and irrelevant. And half of linux.die.net is mirrors of TLDP content which as we can both agree is outdated. Although, I do find die's man page collection useful to read when I'm curious about something on the go.

And yes, I understand you find ArchWiki easier to navigate. But what do you think makes it easier to navigate or what makes TLDP a pain to navigate? These are things I would like to remedy from TLDP