MX Linux Forum

I am considering working over the next few months on an actual MX Users Manual. The concept is to take over the valid parts of the Mepis 11 Manual, fold in and restructure the MX Docs, and produce a Manual as a single html file (as we did before) that can be easily searched. Like the existing manuals, it would aim toward the general user, putting detailed material into links as much as possible.

It would take some time and effort, so I have a couple of questions I would like to hear the Community speak to:

1) The big one: would anybody use it, or would it just "sit on a shelf"?
2) Would it be worth the effort from a larger MX perspective to have such a full user document?
3) Would I be able to find some help on updating (for example, about virtual machines), reviewing, etc?

Any other comments welcome.

1. Yes, some would, others want quick answers through forum posts without doing the research.
2. Yes, a draw for potential new users.
3. I am willing to help review and contribute in areas where I feel I have some expertise.

I think it's a good idea. Not sure how many new users would actually start with the manual - nobody seems to like to read large chunks of info nowadays. But at least they would have something definitive they could resort to, or a place we could refer basic questions to when asked.

Currently the MX info is fragmented, and having a user manual would bring some order and structure to that. Even if new users didn't consult it that much, it would have benefit for ourselves in organizing what the main elements of the project are in one recognizable place.

In order to be really useful, it needs to be more than a one-off effort. Revising the document should be an integrated part of release engineering.

I'm not sure about detailed information being linked. The more info in one place, the better the chance of it being kept up to date and relevant. That could lead to a document so big it's unwieldy, I guess. But I would prefer links being restricted to special use cases.

Wikis seem to be taking over from manuals. But I still prefer a good manual. Wikis tend to be uneven, good in some places, frustratingly incomplete in others, and often way out of date.

I think it is a good idea for the reasons already mentioned.

I would like to see not only html for when online,
but pdf & epub to take along on phones and tablets.
Always handy to have the information available
on another device when having a problem on a PC.

And I will help with proofing, writing and using. :)

1) I believe it would see good use if it were prominently displayed somewhere.
2) Detailed instructions and explanations are always good things.
3) I'd be glad to help where I can.

I would like to see not only html for when online, but pdf & epub to take along on phones and tablets.
Always handy to have the information available on another device when having a problem on a PC.

That's good. I have wondered if we could associate it with a print-on-demand service somewhere so people could have a physical--what's that word?--book for reading.

Jerry3904 wrote:

I would like to see not only html for when online, but pdf & epub to take along on phones and tablets.
Always handy to have the information available on another device when having a problem on a PC.

That's good. I have wondered if we could associate it with a print-on-demand service somewhere so people could have a physical--what's that word?--book for reading.

Similar to an email is sent to "mepis/mx manual" and an auto reply is returned with a pdf attached? Seems to be what I'm getting these days at my work.

Not sure ATM how it would work, just speculating here. Have to get the thing together first--though formatting would have to be kept in mind from the very beginning.

I definitely support the idea - I still occasionally refer to the Mepis 11 Manual and in my early days I used it all the time. I find it much more difficult to find what I want in a wiki. The extensive links at the end of each section worked well for me.

The Mepis 11 Manual is still easily available from the prominent MANUALS tab ot the top of the Forum.

I am willing to help on reviewing, checking and (where I can) writing.

Phil

As a "User Manual", I think some, but not all, of new users would keep it at hand. Especially if it did contain detailed instructions on different programs/features. With the feature to search individual processes, it would be helpful.

A pdf file would make it better for size. And most pdf readers are equipped with a search feature anyway.

A definite YES. If PDF is the decided form, then Scribus is a possibility for setting it out. I have been using this program for a while and
while there's a bit of a learning curve, the results are excellent. I'm very willing to help.

It's all in html ATM

Jerry3904 wrote:It's all in html ATM

It's easy enough to print the html directly for those who want a hard copy
on paper. As there have been suggestions of a PDF version, I was thinking
about using Scribus to produce such a pdf, set out in sections for easier
updating. Apart from the initial writing, formatting etc. we all know that
the biggest issue with any manual is keeping the darned thing up to date.

I don't know what help I can be on such a project but,I am willing to do what I can. I have been wishing for a manual since switching to mx.

Thanks for the feedback!

I have started assembling a base document, deleting stuff from the M11 Manual and moving the MX Docs into larger categories. Current structure and status look like this ATM (1=mostly new, 2=half done or so, 3=essentially done):

Introduction (1)
1: Installation (2)
2: Configuration (2)
3: Software management (3)
4: Command line 101 (3)
5: Advanced use (2)
6: Under the hood (3)
Glossary (with links in text on first appearance) (3)
Appendix (2)

I will have a base assembly finished by the end of the month/year, then we can start on the actual rewriting. Tentative timeline: useable beta by Feb 15 (when it would replace current MX Docs), Final by April 1 for inclusion in MX-15.

I may be missing something, but this looks doable to me without anybody going crazy. We'll see...

Count me in, Jerry.

Jerry - have you got any further on this? I'm thinking that I could have a go at the VirtualBox section and I have a few days spare in the next 2 weeks.

I'm planning on documenting a fresh install of MX-14.3 on my second machine, installing VBox and then creating a WinXP VM and a Linux VM. Although I've done this a number of times, I usually find I have to backtrack to edit something I've missed, so a detailed guide would be useful to me in future. If you haven't made any changes to the M11 section yet, I will start with that.

Phil

Thanks for asking! Yup, Gordon and I have been working hard on this, using Lyx. Attached are screen captures of the draft first page in pdf and html (don't anybody do any text suggestions yet...) deriving from the same Lyx file (so cool!).

A section on VirtualBox setup would be a great help--be sure to consult D-O's two videos on the topic so we are in sync.

Once we get all the formatting and layout stuff in place, I will be posting a list of areas where I could use some help.

I'll anticipate the question, why Lyx?

Lyx is a front end for the typesetting system TeX/LateX. As Jerry wrote, Lyx ouputs in pdf and html(cool), it also can output in .odt, Postscript and a device independent format, DVI. A big advantage in a project like the MX Manual, where updates and changes are to be expected, is that Lyx looks after paragraphs, sections and numbering. If a new section or sub-section has to be added, we just put it in, Lyx does any renumbering automatically.

Yep, there's a bit of learning curve, Lyx nearly drove me bonkers over the first few attempts, but after that, all is sweetnees and light (well nearly).

I think a good uptodate manual is a great idea. A lot of folks like to ask questions in a forum, or google search for answers. New and even seasoned users still need a guide of some sort. I know there has been a few times when I should have been reading and not asking. Having a link to another basic linux guide for newbies would be good to. Like for those coming over from windows. (Linux Guide for Newbies) Perhaps a mx cheat-sheet tailored for mx would be good? Like the Linux cheat sheet. http://www.tuxarena.com/intro/cheatsheet.html

Another good thing might be a complete and very detailed "video guide" on installing, configuring, updating, upgrading, tweaking and making it (mx) your very own.

I don't know what I could do being a basic newbie, but I would be willing to help in any area I can.

Another good thing might be a complete and very detailed "video guide" on installing, configuring, updating, upgrading, tweaking and making it (mx) your very own.

http://www.mepiscommunity.org/videos/mx14

A heads-up to everybody who indicated they could help: Gordon and I are near the end of a full alpha, and will have it posted for the beta work by the end of this week.



I will be looking for specific help in areas such as
--writing (e.g., Basic Use)
--editing (e.g., Installation, Configuration)
--working with links (checking, adding, deleting)
--collecting screencaptures (for the whole thing)

Our deadline will be one month later, at which point it needs to go live as a beta.

TIA

I am NOT suggesting we do this now, for the first edition. That would be too complicated. BUT. . .
. . .as a near-future project, I'd like to suggest that we (and by "we" I mean: ???) put out a Manual for MX that is in HTML 5. The old Mepis Manuals were XHTML + CSS 2. That was IMO the most advanced/versatile on-line/on-disk formating I could work with at the time. Since the design of the Mepis 7 - 11 manuals, HTML5 & CSS 3 have been developed.

The big advantage to html 5 would be the ability to embed both pix and VIDEO . . . from anywhere on the WWW, so long as the user has an internet connection. If s/he isn't online, those functions would be temporarily unavailable to her/him without adversely affecting the rest of the document. We'd probably still have to either go CSS 2 or a very conservative & judicious use of CSS 3, as some of it's "way kewl" features are not yet supported by some browsers. Especially since we are "marketing" MX as a "mid-weight" distro, we have to add the formatting tech advances we can while still keeping in mind the limitations our target users may have.

I've been playing around with HTML 5 and CSS 3, as an excuse that when I finally resurrect SBlinux.org, it should be a state-of-the-art website. Just as in the day that when I'd developed the xhtml/css_2 fly-out menu for SBlinux.org and was then able to use redesigned a version for the Mepis manuals, maybe my current tinkering could be put to use for MX.

Any thoughts, pro or con?

Out of my league, and certainly not even imaginable ATM given the available time.

Jerry3904 wrote:Out of my league, and certainly not even imaginable ATM given the available time.

True -- at this time, not realistically on the table as a realistic project goal that can be slated. After we get the current MX manual project out, I could tinker with it as a side project. If I get something you like, it could possibly serve as a template for continued use & tweaking over the next few years.
According to my records, the last version of the Mepis manual that I actually worked on was v 8.5. You and the crew appear to have done a great job of just using the basic manual template (that we hammered out in producing 7, 8 & 8.5) to come out with version 11. If (and I don't know for sure at this point, of course) but if it's done right, a similar HTML 5 manual template could serve for future versions, by just replacing relevant text and plugging in new sections based on the existing design. A whole different "look" would involve changing the CSS. Changing the content would be relatively simple. That is the new intent: separating style/design from content. CSS (Cascading Style Sheets) will handle almost everything about design and appearance. HTML 5 (HyperText Markup Language) will deal mainly with content. It's similar to XHTML --but more so.

The "semantic content" aspects of HTML 5 are SO improved that --once set up-- maintainence and revision of content does not require the "html guru" reliance to the same extent that has prevailed in previous html versions. I'm not at all tied into the html dev scene, but I'm thinking that they've tried to redesign things so that html should be less esoteric and more accessible to people who know what they want to put up online, but were stymied by the arcane Rube Goldberg formatting solutions that grew up between HTML_1 and HTML _4/XHTML development.

At this stage, it's just about conceiving possibilities. And a very good point was made: "out of my league." That's what webdesign has been! I may have a decent grasp on html_4/xhtml and css_2, but when we were working on redesigning the Mepis website for Warren, I just couldn't be of any use. "Drupal" is no doubt a very efficient platform --but I just can't wrap my head around that approach. Maybe I'm deficient in database savvy. That's the way Drupal works: taking a database approach to html/css. Fortunately, we had a professional Drupal guru (peregrine ) who has been indispensible.

While HTML 5 is not going replace Drupal nor other website/database solutions for maintaining complex websites, it is going to make simple hypertext documents much more "do-able" for more people as time goes on. I'm just starting the conversation about how and why we might consider using the currently upcoming standards. It will require pondering & planning before it gets serious.

Sounds good!

As part of my contribution to the Manual! Please tell me what you use for 1. Browsing 2.Email.

To avoid cluttering this Forum, you can reply directly to me.

Thanks,
Gordon.

Gordon Cooper wrote:As part of my contribution to the Manual! Please tell me what you use for 1. Browsing 2.Email.

To avoid cluttering this Forum, you can reply directly to me.

Thanks,
Gordon.

If that is addressed to Forum members generally, it may be best to start a new topic.

Meanwhile, 1. Iceweasel, 2. Thunderbird.

Phil

Gordon, I'm not clear who you're speaking to here and why you want this information.

Jerry,
Will probably put a short list of the mail & browser programs being used with MX in Section 4.1