research on OpenBSD

[jjstorm]

What package or method do you use to document your research? Do you use a text editor, a local wiki web server, a database or what?

[J65nko]

What kind of research do you mean?

[jjstorm]

Say, I wanted to document the instructions locally on how to install OpenBSD or information about the most popular commands? I should have probably said documentation instead of research.

[jggimi]

I don't write my own "howto" docs. As you will find when you do study someone's published third party "howto", they have short lifespans, and can go out-of-date relatively quickly.

I document local configurations as comments within each configuration file, which are more "why" than "how".

When I want to know how to do something, I start first with the FAQ, then I review man pages, then I look to the OpenBSD Journal. The "howtos" published there were juried by the editors, and were accurate at the time of publication.

[ibara]

Please use the FAQ for things like this. If you don't get your questions answered there try a mailing list.

[TronDD]

Are these documents to be used as instructions for someone else? Or are they just notes to yourself for future reference?

For the former, FAQs and man pages are best in the long run. For the latter, FAQs and man pages are best in the long run with maybe a few sparse reminders in a text file. Usually, once I find the information, it's easier to find it again, than to find notes that may now be out of date or too specific.

Tim.

[Oko]

Originally Posted by jjstorm

What package or method do you use to document your research? Do you use a text editor, a local wiki web server, a database or what?

I use txt2tags lightweight markup language to make HTML pages of my notes. Since txt2tags are text files I keep them in version control system CVS for that matter.

[jjstorm]

Originally Posted by Oko

I use txt2tags lightweight markup language to make HTML pages of my notes. Since txt2tags are text files I keep them in version control system CVS for that matter.

got it, thanks, I will check it out. I also appreciate everyone else's valid points too.

[vanGrimoire]

Lyx offers a lot if you're running a desktop.

[montie]

My $0.02

Mediawiki works best for me if the documentation has to be shared across users.

For security -
1) Webserver is bound to the local LAN only
2) No one has view permissions without entering a login and password in mediawiki

Advantage
- Searchable
- Multiple users at the same time
- Versioning
- ability to upload files

[jjstorm]

Originally Posted by montie

My $0.02

Mediawiki works best for me if the documentation has to be shared across users.

For security -
1) Webserver is bound to the local LAN only
2) No one has view permissions without entering a login and password in mediawiki

Advantage
- Searchable
- Multiple users at the same time
- Versioning
- ability to upload files

Sounds good, but how efficient is to input data into it? Is there a steep learning curve? I have used html before, but I am not great at it.

[raindog308]

Originally Posted by montie

Mediawiki works best for me if the documentation has to be shared across users.

Dokuwiki is an excellent alternative that doesn't require a database running. Mediawiki has more kitchen sink plugins, etc. but Dokuwiki is excellent.

Yes, the user needs to learn how to use a wiki but the language between all of them is very similar if not identical. It's easier than using raw HTML.

Of course, if the notes are just for yourself, you could use anything - text files, OneNote, Evernote, etc.

I keep extensive documentation myself, because the faq/man pages are generic. I don't write down what the flags for some command are - that's man page stuff. Anything that would work the same on any server I don't keep my own notes on.

But what I tend to keep in my notebook are:

(1) Local config stuff. i.e., what the IPs for interfaces should be, Visios showing relationships of servers, RAID configs, etc. Much of it could be determined by system inspection but it's good to have it written down as it should be. Note that some things like which packages are installed on which servers, contents of /etc files, etc. are not things I document because I capture that in backups.

(2) Procedures. For example, adding a new host to backups requires several steps on both the new host and the backup server. I've documented some emergency procedures - e.g., if the root disk fails, how to recover. In many cases, things can be scripted, but not always - or rather, they don't happen often enough that the investment in scripting is worthwhile. Or I haven't had time :-)

(3) Docs on my own sysadmin scripts. Yes, the scripts have comments, etc. but for example, some of them interact with a database and it's nice to have the schema in one place to look at, etc.

(4) Links to faqs/questions/answers. If I have an issue and research and find a solution, I usually document it in case it happens again or I run into it again.

I should emphasize that this is all internal - not stuff published on the Internet.

[vanGrimoire]

Blackbox is good for a system that documents itself as well. There's a little overhead, but it's not worse than html.

The default menu is a great example of a living config file.

http://blackboxwm.sourceforge.net/Bl...ainMenuExample

as an example, last night I installed espeak, for text to speech and saved an example to my blackbox menu as such:

 [exec] (espeak) {urxvt -e sudo -H espeak -a 200 -g 10 -k15 -p 70 -s 165 -v f4 Hello}

When I click that menu item, my pc says "Hello", if I want to see that line I run:

grep espeak /usr/local/share/blackbox/menu

and I get:

 [exec] (espeak) {urxvt -e sudo -H espeak -a 200 -g 10 -k15 -p 70 -s 165 -v f4 Hello}
 # [exec] (fortune) {/usr/games/fortune | espeak}

The second line doesn't work through blackbox, so it's commented out. If I want to write a script in the future that espeaks a fortune then I've got my notes.

[montie]

Originally Posted by jjstorm

Sounds good, but how efficient is to input data into it? Is there a steep learning curve? I have used html before, but I am not great at it.

Even people who are technologically challenged, can input & edit data in a large textarea box. Basic usage learning takes about 30 minutes. Attaching files and making them show up on the page you desire is a pain for non-experienced users. It may not be suitable as the best wiki software (too many config parameters, too many php files, relatively slow etc.), but for users on my research team it does the job well.

Am checking out docuwiki and blackbox both, as suggested by @raindog308 and @vanGrimoire