1

We are currently looking for ways to help the non-programming members of the sysadmin group familiarize themselves with Python scripts used for day-to-day sysadmin tasks.

Does anyone have any suggested documentation tools or best practices that we might find useful for this purpose?

Edit to address S.Lott's comment:

First, my apologies for being too brief on my initial question. My primary goal is to make sure that someone, even a non-programmer, is easily able to troubleshoot my scripts if I'm not in that day or if I leave the organization.

What I'm looking for is practices used by other people who have the "script coder" role in a technical group such as a sysadmin team. For example, before I begin the process of scripting a task, I've gotten into the habit of first writing an article in our shared wiki explaining each step in detail. I then base my Python scripts on the article--using it as pseudo code.

Other examples of the sorts of things I'm looking for:

  • Using tools such as Sphinx to provide easily available doc

  • Having group discussions to go over code before putting in production

  • Allowing group members to first go over the process manually (we usually go this route but perhaps we should make it a more common practice)

Or, just as valuable if not more so, negatives such as:

  • Found that heavy commenting is a waste of time because the logic flow is still foreign to non-programmers

  • Lean toward using pexpect because of the verbosity lost when using high level modules

The above are just examples of things I thought of. Hope this clarifies the question! As always, thanks SO'ers.

Improve this question
3
  • Without details, there's not much to say. Your code is probably pretty good. Do you use docstrings? Do you use Sphinx? What questions do your sysadmins have? Any specific questions? Perhaps they just need a Python tutorial? What specific problems have you encountered? Commented Oct 13, 2010 at 21:09
  • If they are just going to use the scripts, write a man page. If they need to look at the actual code, use doc-strings (which you should be doing anyways). If they need to write other scripts using your code... well, then they're not non-programmers, are they? Commented Oct 13, 2010 at 22:19
  • "Other examples of the sorts of things I'm looking for" What else is there? This list is complete. Item 2 and 3 should be 1 and 2. I don't get what you're worried about. Please provide a specific example of a specific problem you're having. This all sounds like hand-wringing. Please be specific on what you can't do. Commented Oct 14, 2010 at 10:24

2 Answers 2

Reset to default
2

There is a book on this subject - "Python for Unix and Linux System Administration".

And an article on developer works which might provide you the flavor that you may want to follow.

And almost any one, irrespective of how, he is going to apply it, would want to work on the basics of the language itself. There is a good starter on web apart from tutorial that is distributed along with standard python distribution.

Improve this answer
Sign up to request clarification or add additional context in comments.

1 Comment

Thank you for the links! Appreciate the help. Especially the Python for SysAdmins one.
2

I find that using argparse as the basis for script invocation parsing/routing tends to produce a decent first line of documentation. If used as intended, your sysadmins can run some_script --help to get a description of the script's purpose and a summary of its options.

It can be fairly trivial to link the documentation sources used by the parser building code to the actual docstrings of functions and classes in your code and that of the script itself. It depends on the complexity of the script, but this can often be a low-effort way to get sufficient documentation.

Improve this answer

1 Comment

+1 I try to use argparse whenever possible. I wish more people used it for their scripts.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.