Smart Documentation Rewrite

I've started an outline for the.....well book.

Here is what I have for a layout so far.

• Introduction 2
  Who is Smart for 2
  The case for Smart 2
  Understanding packages
  Understanding package management
  What is metadata?
• Features
• Before we begin
  Considerations
  Dependencies
• Installing Smart
  Installing using an existing package manager
  Installing a binary with out a package manager
  Installing from source
• Using Smart
• Packaging for Smart
• Writing patches
• Coding for smart
• Troubleshooting Smart
  Error messages
  Strace reports?
  How to interpret those cryptic error messages

[/b]

Here is your chance to get involved. You get to tell me what you want in this.

Just a thought jon; maybe somebody should do a video tutorial for smart just to cover the basics.
Some of the newer users that are not quite comfortable with the CLI yet would be more apt to get their feet wet after viewing a video of smart in action. I also would like to see links to the list of repo's for smart,but that might not be possible due to all the distro's are different. Can't say enough about warnings about adding some sources to smart that may cause potential problems. Might be a good idea to explain why these should be used with caution in detail.
Hope I've been of service and not a hinderance... :unsure:

Just a thought jon; maybe somebody should do a video tutorial for smart just to cover the basics.
Some of the newer users that are not quite comfortable with the CLI yet would be more apt to get their feet wet after viewing a video of smart in action. I also would like to see links to the list of repo's for smart,but that might not be possible due to all the distro's are different. Can't say enough about warnings about adding some sources to smart that may cause potential problems. Might be a good idea to explain why these should be used with caution in detail.
Hope I've been of service and not a hinderance... :unsure:
[/b]

A video tutorial? Hmm. Interesting.

I hope to cover this in such a way where it's fun to read, easy to understand, and good for everyone. Whether a newbie user, or experienced. Whether a beginning programmer, or an experienced programmer.

I will be going through the code, almost line for line, and explaining it.

I can cover your suggestion on repos under the usage of smart (which I just elaborated on). I'll probably need to either provide the document to y'all, or keep updating you with what I have.

Which would y'all rather have?

If you want the document itself, I'll put it on my site.

I decided to include the link, so y'all can download it and look at it yourself. Maybe even edit it and resubmit it to me
http://downloads.thecompletecomputerresour...t/smartbook.odm

I know there are other folk in this forum who use "smart". So come on people lets put in our 2 cents.
Every comment counts here. Even if you just want to add to something that someone else suggested B)

I have been making a lot of changes. I am not going to have a gazillion smartbook.odm files on the server, so I just over write it. I am no where near done.

I know quite a few of you use smart. I also know quite a few of you have had questions about smart. Here is your chance. By giving me feedback, you can be assured that the document will address your issues.

I downloaded and started reading. This seems to be quite a thing to make btw. I will not spend much time praising you about the initiative, but bluntly start commenting.

Reading he introduction it came to my mind that I still did not know what it is all about. Knowing where I found it i may asume that is has something to do with Linux (or is it also about other OSs). This is nowhere mentioned. Well on page 10 the word Linux is there for the first time (even after the word Windows ).

As an openSUSE user I always use YaST Software Management. Maybe a few words can be added why that is not sufficient/wrong/error ridden or whatever, like you did against some other packages I do not know.

I hope that when you make the above more clear, I will better underdstand why your book to be is something I should read.

I downloaded and started reading. This seems to be quite a thing to make btw. I will not spend much time praising you about the initiative, but bluntly start commenting.

Reading he introduction it came to my mind that I still did not know what it is all about. Knowing where I found it i may asume that is has something to do with Linux (or is it also about other OSs). This is nowhere mentioned. Well on page 10 the word Linux is there for the first time (even after the word Windows ).

As an openSUSE user I always use YaST Software Management. Maybe a few words can be added why that is not sufficient/wrong/error ridden or whatever, like you did against some other packages I do not know.

I hope that when you make the above more clear, I will better underdstand why your book to be is something I should read.
[/b]

I appreciate your brutal honesty. While I do appreciate praise, it is not something I request. I do this, not because of praise or recognition, but because it needs to be done.

At this point, I have taken the current documentation, which I wrote, and pasted it in the book. To give me a start. I can, and do plan, on elaborating.

If criticism is to be offered, it should be constructive. Why mention Windows? I only mention Windows in reference to packages and how they work, and package managers. Smart isn't made to work on Windows, so discussing that would be a waste of time. Only Linux users would be interested in smart.

No, what I am interested in, is clarifying the usage. Last time when I wrote the howto, I basically took the various help files, and put them online, in an orderly fashion. Occasionally, I'd clarify a few of the help files. I wrote the original howto over 2 years ago.

As you can see from the table of contents, I do plan on covering a lot of information. I plan on going through the code, line by line, and explaining it. In order to code for smart, or patch it, or troubleshoot it, understanding the code is essential.

Now, what I am thinking under Using smart, is starting off with channels. Why? Simple, when you have a fresh install of smart, you have a blank config, and no channels. So the first thing that one needs to do, is set up their channels. Now there is a yumsync plugin, and there is also and aptsync plugin. What do these mean? For those who have yum or apt, all they need to do is smart update, and smart will bring in the yum or apt channels. For everyone else, you need to enter them manually. To do this, you need to understand channels and the different formats and types. What's the difference between a urpmi repo and an rpm-md repo and an apt repo? Things like this need to be addressed before going into other details. The next logical step, would be smart update. The smart update, will 1) update the channels and show that new software is available. 2) it will make the list of repos permanent. If you abort the update before it finishes, and before the cache is saved, you will lose the changes made.

This, I hope gives you an idea of where I'm going.

So why did I mention Windows? Simply as a point of reference. Most of us come from Windows. Most of us are familiar with InstallShield. What most don't know is that the InstallShield is just a package manager, and that the package in Windows started off as a source package. By getting people to see this and understand this, it helps with understanding package managers in Linux, and how they work.

I do appreciate your answer. Though it is clear to me that I did not make myself clear enough.

I do not object against you using the word Windows and certainly not in the place you do (I know a lot of people were forced by history/company/ignorance to start there computer live with it) but I wanted to stress that nowhere in the start of the introduction is mentioned that it is written for Linux users/system managers.

You say that that is logical because no other people will know what 'smart' is. I am of a different opinion. As you do show yourself 'smart' is a normal word of the englisg language. As such it will be the subject of searches on the internet. So it is very likely that a lot of people will blunder into your book (when finished). It will be very helpfull when somewhere at the start they will understand if it is of any importance to them.

It is very normal in a manual (written by a professional organisation) to start with statiing who is the audience it is written for.

I am eager to see the manual when finished.

Henk

I do appreciate your answer. Though it is clear to me that I did not make myself clear enough.

I do not object against you using the word Windows and certainly not in the place you do (I know a lot of people were forced by history/company/ignorance to start there computer live with it) but I wanted to stress that nowhere in the start of the introduction is mentioned that it is written for Linux users/system managers.

You say that that is logical because no other people will know what 'smart' is. I am of a different opinion. As you do show yourself 'smart' is a normal word of the englisg language. As such it will be the subject of searches on the internet. So it is very likely that a lot of people will blunder into your book (when finished). It will be very helpfull when somewhere at the start they will understand if it is of any importance to them.

It is very normal in a manual (written by a professional organisation) to start with statiing who is the audience it is written for.

I am eager to see the manual when finished.

Henk
[/b]

I get what you're saying. When I put the chapter in "Who is smart for", I only put in one line as a place holder. I fully intended on adding more to it. I'll be uploading a current revision shortly.